Referencia de errores
Formato de error normalizado y los códigos más frecuentes.
Formato
Todo error sigue la misma estructura JSON, sea cual sea el endpoint:
json
{
"error": {
"code": "insufficient_credits",
"message": "Solde de credits insuffisant ou budget mensuel du projet depasse.",
"request_id": "9480fe92-f68e-4731-b98e-d35a5e8b9819",
"details": {}
}
}request_id identifica la solicitud de principio a fin a través de los servicios — útil de proporcionar si nos contactas por un error inesperado.
Códigos frecuentes
| HTTP | código | Significado |
|---|---|---|
| 401 | missing_api_key | Cabecera Authorization ausente. |
| 401 | invalid_api_key | Clave API inválida, revocada o expirada. |
| 403 | insufficient_scope | La clave no tiene el scope requerido para esta categoría. |
| 403 | not_a_member | No perteneces a esta organización. |
| 403 | csrf_check_failed | Falta la cabecera de seguridad (cookie de sesión, no aplicable al uso de clave API). |
| 404 | model_not_found | routing_strategy "manual" con un model desconocido en el catálogo. |
| 404 | no_model_available | Ningún modelo cumple los criterios solicitados. |
| 402 | insufficient_credits | Saldo de créditos insuficiente o presupuesto mensual del proyecto superado. |
| 409 | conflict | Estado incompatible con la acción (p. ej. conversación de agente no idle). |
| 422 | validation_error | Cuerpo de solicitud inválido (campo faltante, tipo incorrecto...). |
| 429 | rate_limit_exceeded | Demasiadas solicitudes para esta clave — ver Límites de tasa. |
| 503 | all_providers_unavailable | Todos los proveedores candidatos han fallado (ver Enrutamiento y failover). |
En los SDKs
Los SDKs oficiales convierten cada tramo de estado HTTP en una clase de error tipada (AuthenticationError, PermissionDeniedError, NotFoundError, InsufficientCreditsError, ConflictError, ValidationError, RateLimitError, ServerError), todas exponiendo .code, .status, .requestId y .details además del mensaje. Ver SDK de JavaScript / SDK de Python.