Developer guide
Códigos de error
Acciones y reglas de reintento por código de estado
Esta página resume los códigos de estado que devuelve la puerta de enlace, su significado y las acciones correspondientes a cada código.
Si el upstream devuelve un código 4xx o 5xx, se reenvía tal cual; en los demás casos, se aplica la tabla siguiente.
También se documentan el formato del cuerpo de error de las dos especificaciones compatibles, las reglas de error.type compatible con Anthropic y la pantalla de la consola para consultar los límites y el uso.
Código de estado
| Código | Significado | Acción |
|---|---|---|
| 400 | Error en los valores de la solicitud. limit de la lista de modelos compatibles con Anthropic está fuera del rango de 1 a 1000, o se intentó reanudar una respuesta guardada mediante GET /responses/{responseId}?stream=true | Corrija el valor para que esté dentro del rango. Consulte las respuestas guardadas sin stream. |
| 401 | La clave no existe, o está vencida o revocada | Verifique el estado de la clave en la pantalla de claves de API y compruebe el nombre del encabezado y el prefijo Bearer. |
| 403 | No hay permiso para acceder al modelo, se superó el límite de uso, no hay créditos o no es el propietario de la voz | error.message indica el motivo específico. Consulte los valores en la pantalla de la sección sobre límites y uso que aparece más abajo. |
| 404 | El modelo no existe o no se puede acceder a él con esta clave (incluidos los modelos cuyo soporte finalizó), la ruta no existe o el resultado de CleviDrive superó el periodo de retención de 3 días | Primero compruebe la lista de modelos disponibles mediante GET /models. Compare la ruta con la tabla de la página Cómo realizar llamadas a la API. |
| 408 · 409 · 413 | Tiempo de espera agotado del upstream, congestión o tamaño de solicitud excedido. Para las rutas de audio y voz, el tiempo límite es de 5 minutos y el tamaño máximo de la solicitud es de 28 MiB | Si 409 incluye Retry-After, espere ese tiempo. Para 413, divida la solicitud antes de enviarla. |
| 429 | El proveedor upstream aplicó un límite de velocidad | Si se incluye Retry-After, sígalo tal cual; si no, reintente con retroceso exponencial. |
| 5xx | Error temporal de la puerta de enlace o del upstream (incluido 503) | Reintente con retroceso exponencial. Si el problema se repite, infórmelo en la ayuda y en contacto, junto con X-Request-Id. |
Reintentos
La puerta de enlace no genera sus propios 429 ni reintenta silenciosamente las respuestas del upstream ni las pone en cola.
El cliente se encarga de esperar y reintentar.
| Código | Tiempo de espera | Qué hacer después |
|---|---|---|
| 409 | Si existe Retry-After, esperar ese tiempo | Volver a enviar la misma solicitud. |
| 429 | Si existe Retry-After, esperar ese tiempo; de lo contrario, aplicar retroceso exponencial | Volver a enviar la misma solicitud. |
| 5xx | Retroceso exponencial | Si se repite, ponerse en contacto con soporte. |
| 413 | Sin espera | Dividir la solicitud. |
Cuerpo del error
La forma del cuerpo del error varía según la especificación. Los errores ascendentes se envían depurados, conservando únicamente el mensaje; no se incluyen la pila ni los campos internos.
Este es el cuerpo de la ruta compatible con OpenAI.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}Este es el cuerpo de la ruta compatible con Anthropic. error.type se determina mediante el código de estado.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| Código de estado | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| Otros códigos | api_error |
Comprobar límites y uso
Los límites varían según el espacio de trabajo. Confirme el motivo del 403 en error.message y, después, consulte las cifras en las pantallas siguientes.
| Qué comprobar | Pantalla de la consola |
|---|---|
| Límites aplicados a mi espacio de trabajo | Límites de uso asignados en el resumen |
| Rango permitido por el plan y saldo | Plan y créditos |
| Uso real (llamadas por modelo y por clave, créditos estimados descontados) | Uso |
| Estado de la clave (si expiró o fue revocada) | Clave de API |