Errores de la API

Todos los errores de la API usan Content-Type: application/problem+json y RFC 9457 Problem Details. La Energy API no tiene ningún otro formato de error.

Sobre

{"type":"https://rentron.xyz/docs/errors/codes#energy_order_not_found","title":"Not Found","status":404,"detail":"Order was not found.","code":"energy_order_not_found"}

Campo	Tipo	Para qué sirve
type	cadena	URI estable del tipo de error.
title	cadena	Categoría HTTP breve.
status	entero	Código de estado HTTP repetido en el cuerpo.
detail	cadena	Explicación legible y segura.
code	cadena	Código estable para que ramifique tu aplicación.
field	cadena o null	El campo no válido, cuando aplica.
errors	array o null	Varios errores de campo con code, field y message.

Ramifica la lógica de tu aplicación con code. Puedes mostrar detail a un operador como último recurso, pero no lo interpretes nunca.

Varios errores de campo

errors solo aparece cuando fallan dos campos o más a la vez. Si falla uno solo, la respuesta llega plana: el código concreto en el nivel superior, el nombre del campo en field y ningún array errors.

{"type":"https://rentron.xyz/docs/errors/codes#field_invalid_format","title":"Bad Request","status":400,"detail":"Request validation failed.","code":"field_invalid_format","field":"address"}

A partir de dos campos, el código del nivel superior pasa a ser validation_failed y cada campo se lista por separado:

{"type":"https://rentron.xyz/docs/errors/codes#validation_failed","title":"Bad Request","status":400,"detail":"Request validation failed.","code":"validation_failed","errors":[{"code":"field_invalid_format","field":"target_address","message":"Request validation failed."},{"code":"field_must_be_positive","field":"duration_minutes","message":"Request validation failed."}]}

field nombra el valor que no pasó la validación, y ese nombre no siempre coincide con el del campo de la petición: address vuelve como target_address. Ramifica con code y lee field como pista para tus registros.

Códigos habituales

Código	HTTP	Qué hacer
malformed_request	400	Corrige el JSON y los tipos de los campos.
field_invalid_format	400	Falló un campo; lee field y corrígelo.
validation_failed	400	Fallaron dos campos o más; lee errors.
unauthorized	401	Revisa el HMAC, la marca de tiempo y la credencial.
energy_order_not_found	404	Da el pedido por no disponible; la propiedad no se revela.
energy_order_idempotency_conflict	409	No reutilices un mismo ID para otro pedido.
energy_price_changed	409	Pide una cotización nueva y envíala otra vez; no se creó ningún pedido ni se retuvo ningún TRX.
insufficient_balance	409	Recarga el saldo de la cuenta antes de reintentar.
energy_intake_disabled	409	Los pedidos nuevos están en pausa; reinténtalo más tarde.
payload_too_large	413	Reduce el cuerpo de la petición.
unsupported_media_type	415	Envía application/json.
rate_limited	429	Respeta Retry-After.
energy_api_unavailable	503	Reintenta con espera creciente.

Cuando la petición llega lo bastante lejos como para nombrar la causa, el 401 trae además un código más preciso: authorization_missing, authorization_malformed, timestamp_missing, timestamp_expired, invalid_credentials o ip_not_allowed. En todos ellos la acción es la misma: arregla la firma o la credencial y no repitas la petición sin cambios.

Manejador seguro

if (!response.ok) {
  const problem = await response.json();
  if (response.status === 429) scheduleRetry(response.headers.get('Retry-After'));
  throw new RentronApiError(problem.code, problem.detail, problem.errors ?? []);
}