Guías principales
Manejo de errores de la API
Lea los códigos de error, reintente solo cuando sea útil y conserve el Request ID
Maneje los errores mediante el estado HTTP y el code. El message está escrito para personas y puede cambiar sin previo aviso.
Las respuestas de Chat Completions utilizan un objeto error al estilo de OpenAI. Anthropic Messages y Gemini mantienen sus propios formatos de error, por lo que no debe utilizar un único analizador para toda la API de TokenLab.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Solo message y type están siempre presentes en los errores compatibles con OpenAI creados por TokenLab. Otros campos aparecen cuando son relevantes.
Códigos de estado
| Estado | Significado | Acción típica |
|---|---|---|
400 | Un campo, ID de modelo o entrada no es válido | Corrija la solicitud; no la repita sin cambios |
401 | La API key falta, no es válida, ha caducado o ha sido revocada | Reemplace la clave |
402 | El saldo o el límite de la API-key es demasiado bajo | Recargue, aumente el límite o reduzca la solicitud |
403 | Esta clave no puede utilizar el recurso o modelo | Cambie los permisos de la clave o el modelo |
404 | El recurso no existe o ya no está disponible | Verifique el ID y la API key que lo creó |
413 | La solicitud o el archivo subido es demasiado grande | Reduzca la entrada al límite documentado del modelo o endpoint |
429 | Se alcanzó el límite de solicitudes | Espere según Retry-After |
500–504 | Servicio no disponible o fallo de red | Reintente solo con retryable: true; respete retry_after y limite los intentos |
Códigos de error comunes
| Código | Qué significa | Qué cambiar |
|---|---|---|
invalid_api_key | La clave API falta, no es válida, está inactiva o fue revocada | Verifique el encabezado Authorization y el valor de la clave |
expired_api_key | La clave API ha caducado | Cree o seleccione una clave activa |
insufficient_balance | El saldo de la cuenta no puede cubrir la solicitud | Añada fondos, reduzca la solicitud o elija un modelo de menor precio |
quota_exceeded | La API key alcanzó su propio límite | Aumente el límite de esa clave o use una clave autorizada diferente |
model_not_allowed | La clave no puede usar el modelo solicitado | Actualice la lista de modelos de la clave o elija un modelo permitido |
model_not_found | El ID del modelo es desconocido o no está disponible | Lea /v1/models y use un ID de modelo actual |
context_length_exceeded | La entrada es más larga de lo que acepta el modelo | Elimine historial o elija un modelo con una ventana de contexto mayor |
rate_limit_exceeded | Se enviaron demasiadas solicitudes en la ventana actual | Espere según Retry-After |
payload_too_large | El cuerpo de la solicitud o el archivo excede el límite del endpoint | Reduzca o comprima la entrada |
all_channels_failed | El modelo seleccionado no puede atender esta solicitud | Reintente solo con retryable: true; respete retry_after y limite los intentos |
timeout_error | La solicitud no terminó a tiempo | Reintente solo cuando la operación sea segura de repetir |
503 all_channels_failed o 503 delivery_tier_unavailable no siempre indica un fallo temporal. Si no hay oferta para la operación en el nivel Delivery seleccionado, retryable es false y se omite retry_after. No repita la misma solicitud. Consulte la disponibilidad de la operación y de Delivery mediante GET /v1/models antes de elegir otro modelo. Los nombres similares no garantizan disponibilidad; se omiten las alternativas no verificadas.
Algunos errores compatibles con OpenAI incluyen campos opcionales como did_you_mean, suggestions, alternatives, hint, retryable o retry_after. Consulte Errores sobre los que los agentes pueden actuar.
Cuando una solicitud se ejecutó por una ruta Official y el servicio upstream rechazó la propia solicitud, por ejemplo por una entrada que no acepta o por una decisión de política de contenido, el error también incluye upstream: el message del upstream tal como lo informó, además de code y source (el nombre del servicio upstream) cuando se conocen. Los errores de Anthropic Messages y Gemini incluyen el mismo objeto dentro de su propio error. Sigue decidiendo según code y type; los valores de upstream.code los define el servicio upstream y pueden cambiar.
Decisiones de reintento
| Error | ¿Repetir la misma solicitud? |
|---|---|
400, 401, 402, 403, 404, 413 | No. Cambie la solicitud, las credenciales, el saldo, los permisos o la entrada. |
429 | Sí, después de la demora proporcionada por el servidor. |
500–504 | Reintente solo con retryable: true; respete retry_after y limite los intentos |
| Conexión cerrada antes de cualquier respuesta | A veces. Para operaciones de creación, verifique si ya existe una tarea o efecto secundario. |
| Flujo interrumpido después de recibir salida | No lo llame una respuesta completa. Repetir puede generar una salida diferente o un segundo cargo. |
Para la creación de imágenes, video, música, 3D y mundos, guarde el ID de la tarea tan pronto como se devuelva. Si una solicitud de creación agota el tiempo de espera, verifique el registro de la tarea antes de enviar otra solicitud de creación.
Conserve el Request ID
Los encabezados de respuesta incluyen un Request ID para el seguimiento. Guárdelo junto con el endpoint, el modelo, la hora y su propio ID de usuario o trabajo. Para trabajos asíncronos, guarde también task_id y billing_transaction_id cuando estén presentes.
Al contactar al soporte, incluya esos IDs y un ejemplo redactado. Nunca envíe API keys, tokens de gestión, medios privados, URLs firmadas o prompts privados completos.