Documentación de HopBaseCódigos de error y reintentos
Estructura de las respuestas de error de HopBase, qué significa cada código de estado y si se puede reintentar, cómo se manifiestan los fallos en streaming y qué datos incluir al reportar un problema.
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": "…" } }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 de la cuenta agotado; cuota de la clave agotada; el saldo no cubre la reserva al enviar un vídeo | Tras recargar | Recarga o amplía la cuota de la clave; no reintentes en bucle |
| 403 | El plan restringe qué clientes pueden llamar, o la capacidad no está habilitada | No | Usa un cliente o un plan que lo admita |
| 404 | El modelo no está en el plan de esta clave, la ruta no corresponde, o el plan se ha retirado | No | Llama a GET /v1/models con esta clave para confirmar el ID; para rutas consulta Base URL y protocolos |
| 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 modelo está limitado en este momento | Sí | Reintenta según Retry-After y reduce la concurrencia |
| 499 | El cliente cortó la conexión antes de terminar (parada manual o tiempo de lectura agotado) | Sí | Usa streaming para salidas largas y amplía el tiempo de lectura del cliente |
| 502 / 503 | El modelo no está disponible temporalmente; el reintento automático tampoco lo consiguió | Sí | Espera y reintenta, o cambia a otro modelo de la misma familia |
| 504 | La petición agotó el tiempo en el servicio | Sí | Espera y reintenta; para trabajos largos usa streaming o los endpoints asíncronos |
Hay un 404 que en realidad significa «no disponible ahora mismo»
Si recibes Model "X" is not supported by any configured account in this group, llama primero a GET /v1/models con la misma clave. Si el modelo aparece en la lista, solo está temporalmente no disponible: trátalo como un 502 / 503. Solo si no aparece el plan realmente no incluye ese modelo.
Reglas de reintento
- Nunca reintentes sin cambios: 400, 402, 403, 404, 413, 422. Corrige antes la petición, la configuración o el saldo.
- 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.
- El 429 trae pistas de reintento:
Retry-After(segundos) yRetry-After-Ms(milisegundos). Respétalas cuando estén presentes. - No reenvíes una tarea asíncrona ya aceptada: un envío de vídeo o de imagen asíncrona aceptado ya creó la tarea; reenviarlo crea tareas adicionales que se facturan por separado. Consulta el estado 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:
- Protocolo OpenAI:
event: error, oresponse.faileden el protocolo Responses. - Protocolo 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.
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
Escríbenos con esos datos y podremos rastrear la petición directamente.
Concurrencia, tiempos de espera y facturación
Límites de concurrencia de HopBase, comportamiento de los tiempos de espera por endpoint y valores recomendados en el cliente, límite de tamaño de la petición y cuándo se factura exactamente.
Solución de problemas
Diagnostique rápidamente errores de protocolo, clave, modelo y entorno.