Errores y reintentos

Los errores se devuelven como JSON con un código error estable y legible por máquina, junto con el estado HTTP correspondiente.

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

Códigos de error

HTTP	error	¿Reintentar?	Notas
400	invalid_request	No	Un parámetro falló la validación — corrige la petición.
401	missing_api_key / unknown_api_key	No	Consulta Autenticación.
403	inactive_api_key / account_blocked	No	Clave deshabilitada o cuenta suspendida.
402	insufficient_credits	No	Recarga. El cuerpo incluye required y balance.
429	rate_limited	Sí, tras retry_after_ms	Superaste tu límite por minuto.
409	request_in_progress	Sí	Una petición idempotente idéntica sigue en ejecución.
422	(conflicto de idempotencia)	No	Se reutilizó una Idempotency-Key con un cuerpo diferente.
503	service_temporarily_unavailable / too_many_concurrent_requests	Sí, con backoff	Límite de capacidad transitorio.
504	result_timeout	Sí	La obtención upstream superó deadline_ms.

Guía de reintentos

• Reintenta 429 / 503 / 504 / 409 con backoff exponencial. Cuando retry_after_ms está presente, espera al menos ese tiempo antes de reintentar.
• Nunca reintentes 400 / 401 / 402 / 403 — la petición no tendrá éxito hasta que la cambies.
• Los SDKs oficiales ya reintentan los errores transitorios por ti (2 reintentos por defecto) y exponen una bandera retryable en el error.

Cabeceras de respuesta útiles

x-ratelimit-remaining indica cuántas peticiones quedan en el minuto actual. x-idempotent-replay: true indica que una respuesta se reprodujo desde la caché de idempotencia (no se te cobró de nuevo).