Errores

Cada respuesta de error de la API de Aeses tiene la misma forma. Ramifica por los campos type y code — no por el message legible por humanos, que puede cambiar.

Forma de la respuesta

Respuesta de error

{
"error": {
  "type": "invalid_request_error",
  "code": "insufficient_balance",
  "message": "Available USDC balance is 12.50 — requested 50.00.",
  "param": "amount",
  "request_id": "req_01HXYZ7M2P5RT4VG3K8AQWE9FN",
  "doc_url": "https://docs.aeses.io/errors#insufficient_balance"
}
}

| Campo | Siempre presente | Descripción | | ------------ | ---------------- | --------------------------------------------------------------------------- | | type | Sí | Categoría de alto nivel. Úsala para decidir el comportamiento de reintento. | | code | Sí | Código estable y legible por máquina. Úsalo para lógica de ramificación. | | message | Sí | Texto en inglés legible por humanos. No es estable — no lo parsees. | | param | Cuando aplica | Parámetro de la solicitud que causó el error. | | request_id | Sí | Devuelto en cada respuesta. Inclúyelo al contactar a soporte. | | doc_url | Cuando aplica | Enlace directo a la documentación de este código. |

Tipos de error

| Tipo | HTTP | ¿Reintentar? | Significado | | ----------------------- | ----- | ------------------------------- | ------------------------------------------------------ | | authentication_error | 401 | Nunca — corrige la clave antes. | Clave API ausente, inválida o revocada. | | forbidden | 403 | Nunca. | Clave válida pero sin permiso para este recurso. | | invalid_request_error | 400 | Nunca — corrige el payload. | Violación de validación, esquema o regla de negocio. | | not_found | 404 | Nunca. | El recurso solicitado no existe. | | idempotency_error | 409 | Nunca — genera una nueva clave. | Clave de idempotencia reutilizada con cuerpo distinto. | | rate_limit_error | 429 | Sí, con backoff. | Demasiadas solicitudes. Respeta Retry-After. | | api_error | 500 | Sí, con backoff. | Error interno del servidor. | | service_unavailable | 503 | Sí, con backoff. | Caída temporal. Reintenta tras una pausa breve. |

Estrategia de reintentos

Nunca reintentes en errores 4xx, salvo 429.
Reintenta con backoff exponencial en 429, 500 y 503. Empieza en 500ms, duplica hasta 8s y abandona tras 5 intentos.
Envía siempre la misma Idempotency-Key en cada reintento para que la operación se ejecute como mucho una vez. Consulta Idempotencia.

Códigos de error comunes

| Código | Tipo | Descripción | | ----------------------------- | ----------------------- | -------------------------------------------------------------------- | | api_key_missing | authentication_error | Header x-api-key ausente. | | api_key_invalid | authentication_error | La clave no existe o fue revocada. | | key_environment_mismatch | authentication_error | Clave de prueba usada en modo live (o viceversa). | | parameter_missing | invalid_request_error | Falta un parámetro requerido. param indica cuál. | | parameter_invalid | invalid_request_error | Un parámetro tiene tipo o formato incorrecto. | | unsupported_asset | invalid_request_error | La combinación asset/chain solicitada no está soportada. | | insufficient_balance | invalid_request_error | La cuenta no tiene saldo suficiente para la operación. | | withdrawal_below_minimum | invalid_request_error | El monto del retiro está por debajo del mínimo de la red. | | invalid_destination_address | invalid_request_error | La dirección de destino está mal formada o no es válida para la red. | | idempotency_key_reused | idempotency_error | La Idempotency-Key se usó con un cuerpo de solicitud distinto. | | rate_limited | rate_limit_error | Demasiadas solicitudes en la ventana. Respeta Retry-After. | | internal_error | api_error | Fallo inesperado del servidor. Seguro de reintentar. |

Siempre loggea `request_id`