Códigos de error y reintentos

Interprete los errores de HopBase, incluidos los de streaming, y decida cuándo reintentar.

Para localizar un síntoma concreto usa Solución de problemas; esta página es la referencia completa. Los límites de concurrencia, los tiempos de espera y la facturación están en Concurrencia, tiempos de espera y facturación.

Estructura de la respuesta de error

Protocolo OpenAI (/v1/chat/completions, /v1/responses, /v1/images/*, /v1/video/*):

{
  "error": {
    "message": "…",
    "type": "invalid_request_error",
    "code": "insufficient_quota"
  }
}

Protocolo Anthropic (/v1/messages):

{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "…" }
}

La estructura Anthropic no trae code. Los errores de validación de la clave (401, 402 de cuota, 403 de cuenta) usan la estructura OpenAI también en /v1/messages. El idioma del mensaje sigue la cabecera Accept-Language y por defecto es inglés. En tu código decide según el código HTTP y code, nunca según el texto del mensaje.

Códigos de estado

Código	Causa habitual	¿Reintentable?	Qué hacer
401	Falta la clave, está incompleta, desactivada o caducada	No	Copia la clave de nuevo desde Claves API en la consola, o crea otra
402	Saldo o cuota de clave, miembro o departamento agotados; el saldo no cubre la reserva al enviar un vídeo	Tras recargar	Comprueba cuánto puede gastar aún la clave con `GET /v1/usage`; luego recarga o amplía la cuota; no reintentes en bucle
403	Cuenta o miembro desactivado, sin permiso o sin grupo, o capacidad no habilitada	No	Contacta al administrador, o usa una clave de un grupo que lo admita
404	El modelo no está en el grupo de esta clave, la ruta no corresponde, o el grupo está fuera de servicio	No	Llama a `GET /v1/models` con esta clave para confirmar el ID; para rutas consulta Base URL y protocolos; los ID retirados y sus sustitutos están en el registro de cambios de modelos
413	Cuerpo de la petición mayor de 60 MB	No	Comprime el material o envía una URL cuando el modelo lo admita
429	Límite de concurrencia de la cuenta o de la clave, o el servicio está ocupado	Sí	Reintenta según `Retry-After` y reduce la concurrencia
499	Solo en los registros de la consola: el cliente cortó antes y no lo recibe	—	Usa streaming para salidas largas y amplía el tiempo de lectura del cliente
502 / 503	El servicio no está disponible temporalmente; los reintentos automáticos no lo consiguieron	Sí	Espera y reintenta, o cambia a otro modelo de la misma familia
504	La petición agotó el tiempo	Sí	Espera y reintenta; para trabajos largos usa streaming o los endpoints asíncronos

Lista de códigos de error

# El campo code de las respuestas con estructura OpenAI. Un 400 emitido por el propio modelo puede llevar el code de ese modelo.
Estado  code                          Significado                                          Reintento
401     missing_api_key               No se envió clave                                    No
        invalid_api_key               Clave no válida o eliminada                          No
        api_key_expired               Clave caducada                                       No
402     insufficient_quota            Saldo o cuota de clave / miembro / departamento agotados   Tras recargar
        insufficient_balance          Vídeo: el saldo no cubre lo reservado + esta estimación    Al terminar tareas / recargar
403     account_disabled              Cuenta desactivada                                   No
        member_disabled               Cuenta de miembro desactivada                        No
        member_group_forbidden        El miembro no puede usar el grupo de esta clave      No
        api_key_misconfigured         Clave sin grupo                                      No
        image_generation_disabled     Generación de imágenes no habilitada en el grupo     No
        middleware_denied             Rechazada por la política del gateway                No
404     model_not_found               El grupo no admite este modelo                       No
        model_not_served              El grupo no ofrece este modelo                       No
        group_offline                 Grupo fuera de servicio                              No
        route_not_found               Ruta no admitida para esta clave                     No
400     invalid_request               Cuerpo ilegible o no es objeto JSON, falta model, messages vacío   No
413     request_too_large             Cuerpo mayor de 60 MB                                No
429     user_concurrency_limit        Límite de concurrencia de la cuenta (Retry-After: 1) Sí
        apikey_concurrency_limit      Límite de concurrencia de la clave (Retry-After: 1)  Sí
        all_routes_rate_limited       Servicio ocupado                                     Sí
        upstream_rate_limit           Servicio ocupado                                     Sí
502     upstream_error                Servicio no disponible temporalmente                 Sí
503     no_available_route            Servicio ocupado                                     Sí
        no_available_account          Servicio ocupado (ver la excepción de sesión abajo)  Sí*
        all_routes_failed             Servicio no disponible temporalmente                 Sí
        plugin_unavailable            Servicio no disponible temporalmente                 Sí
        service_unavailable           Servicio de autenticación no disponible un momento   Sí
504     upstream_timeout              Tiempo agotado                                       Sí

Reglas de reintento

Nunca reintentes sin cambios: 400, 402, 403, 404, 413, 422. Corrige antes la petición, la configuración o el saldo. El 404 es definitivo: la indisponibilidad temporal devuelve 429 / 5xx, nunca 404.
Reintenta con espera creciente: 429, 502, 503, 504 y los flujos interrumpidos. Se sugieren 2 s, 5 s y 15 s, como máximo tres intentos. Excepto el 503 de sesión que "can no longer be resumed": quita previous_response_id y empieza una conversación nueva.
El 429 trae pistas de reintento: Retry-After (segundos) y Retry-After-Ms (milisegundos). Respétalas cuando estén presentes.
No reenvíes una tarea asíncrona ya aceptada: cada reenvío es otra tarea facturada aparte; consulta por sondeo.

Fallos en streaming

En cuanto una respuesta en streaming empieza, el código HTTP ya es 200 y no cambia. Los fallos posteriores llegan como eventos:

Chat Completions   data: {"error": {…}}      (sin línea event:)
Responses          event: response.failed    (response.error.code: rate_limit_exceeded / server_error / invalid_prompt)
Anthropic          event: error

Gestiona los eventos de error dentro del bucle de lectura. La salida parcial no se puede reanudar: vuelve a lanzar la petición completa.

Fallos de tareas asíncronas

Un envío rechazado devuelve un 4xx normal y no crea tarea. Si la tarea falla tras aceptarse, el sondeo sigue dando 200 con status: "failed" y el motivo en error.message (tareas de imagen: una cadena error): sin code (las tareas de Kling y Midjourney sí devuelven un error.code estable, como input_sensitive, invalid_request o generation_failed) y sin facturar. No reenvíes sin cambios los fallos de moderación o de parámetros. Consumo en la consola muestra la categoría y qué hacer:

Moderación   input_sensitive, safety_rejected …                          cambia prompt / material
Parámetros   prompt_required, upstream_invalid_request, reference_* …    corrige parámetros
Tiempo       límites por familia en Concurrencia, tiempos de espera…     reenvía
Interrupción task_interrupted                                            reenvía

Al reportar un problema

La cabecera de respuesta x-request-id (todas las respuestas la llevan e identifica esa petición concreta)
La hora (con zona horaria) y el ID del modelo
El texto completo del error y el código HTTP

La consola oculta el texto original de los fallos del servicio, así que rastreamos por x-request-id. Escríbenos con esos datos y podremos rastrear la petición directamente.

Próximos pasos

Solución de problemas: busque un mensaje de error
Concurrencia, tiempos de espera y facturación: límites de concurrencia, tiempos de espera y reglas de facturación
API de cuenta y catálogo: consulte saldo, uso y catálogo de modelos por API

En esta página