Códigos de error
Descifra cada error de OneProvider: qué significa cada código, el mensaje exacto, límites de tiempo, errores durante el streaming y cuándo reintentar.
Qué significa cada código de estado, el mensaje exacto que verás y qué hacer a continuación.
Todos los modelos, capacidades y precios Índice de la documentación para agentes de IA:https://oneprovider.dev/docs/llms.txt Forma del error
Todos los errores son JSON con la misma forma en todos los endpoints (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). El error de saldo además incluye code:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}Los SDK de OpenAI leen error.message de este cuerpo como siempre, así que ves el mismo texto en cualquier cliente.
Códigos de estado
| Estado | error.type | Mensaje y significado | Qué hacer |
|---|---|---|---|
| 400 | invalid_request_error | La solicitud está mal formada: JSON no válido, falta un campo o un valor no permitido. El mensaje indica cuál es el problema. | Corrige lo que señala el mensaje y vuelve a enviarla. Si la reenvías sin cambios, devuelve el mismo error. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum La entrada es mayor que la ventana de contexto de este modelo. N y M dependen del modelo. | Acorta el historial o los archivos adjuntos, o elige un modelo con más contexto. Claude Code compacta la conversación por sí solo cuando ve este error. |
| 400 | invalid_request_error | Model X is not available on this API key El plan de tu clave no incluye este modelo. | Elige un modelo de la lista de GET /v1/models o de la página de precios. |
| 401 | authentication_error | Invalid API key API key is required Falta la clave, está mal escrita o se envió en un encabezado equivocado. | Envía la clave sk-… tal cual, sin comillas ni espacios, en x-api-key o en Authorization: Bearer. |
| 401 | authentication_error | API key is disabled La clave está desactivada o la cuenta está inactiva. | Revisa la clave en tu panel (página Claves) o escribe a @Oneproviderhelpbot. |
| 403 | permission_error | API key expired La clave pasó su fecha de vencimiento. | Renueva la clave o emite una nueva en tu panel (página Claves). |
| 404 | not_found_error | The requested API endpoint does not exist Normalmente es una base URL incorrecta, por ejemplo /v1/v1 en la ruta. | Claude Code y los SDK de Anthropic: https://api.oneprovider.dev. Los SDK de OpenAI y los clientes compatibles con OpenAI: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit El cuerpo de la solicitud supera los 32 MB. | Envía imágenes y archivos más pequeños o menos numerosos, o divide el trabajo en varias solicitudes. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev Se agotó el saldo del panel o el límite de gasto de la clave. El cuerpo trae error.code insufficient_quota y la respuesta tiene el encabezado x-should-retry: false. | No reintentes. Recarga el panel (bot o app.oneprovider.dev) o sube el límite de la clave, y vuelve a enviar la solicitud. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Demasiadas solicitudes en poco tiempo. Puede incluir un encabezado Retry-After. | Espera los segundos de Retry-After si está presente; si no, reintenta con una pausa creciente. Si sigue ocurriendo, envía menos solicitudes en paralelo. |
| 500, 502 | server_error | Service temporarily unavailable; retry later Un fallo temporal por nuestra parte. | Reintenta con una pausa creciente. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Temporal. No hay nada mal en tu clave ni en tu solicitud. | Reintenta con una pausa creciente; normalmente se resuelve en menos de un minuto. |
| 504 | server_error | Service timed out; retry later La solicitud superó un límite de tiempo (ver abajo). | Reintenta. Para respuestas largas, activa stream: true. |
Límites de tiempo
- Una solicitud sin streaming debe empezar a responder en un máximo de 6 minutos.
- Cualquier solicitud, incluidas las de streaming, tiene un tope de 10 minutos.
- Para generaciones largas usa
stream: true: un stream empieza a responder de inmediato. Si una respuesta necesita más de 10 minutos, divide la tarea.
Errores dentro de un stream
Cuando un stream ya empezó, el estado ya es 200, así que el error llega como un evento. La Messages API envía un fragmento event: error con el mismo cuerpo de error; la Responses API envía un evento response.failed con el motivo en response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Trátalo como el código de estado correspondiente. La respuesta parcial está incompleta: si el error admite reintento, envía de nuevo la solicitud completa.
Cuándo reintentar
- Corrige primero, no reintentes: 400, 401, 403, 404, 413 y 429 con
insufficient_balance. La misma solicitud falla igual hasta que cambies la solicitud, la clave o el saldo. - Reintenta con una pausa creciente: 429
rate_limit_error, 500, 502, 503, 504. Por ejemplo 1 s, 2 s, 4 s y así hasta un minuto, con un poco de variación aleatoria. Si hayRetry-After, espera al menos ese tiempo. - Respeta
x-should-retry: false. Los SDK oficiales de Anthropic y OpenAI ya lo hacen, así que no reintentan el error de saldo. - Consulta cuánto queda con
GET /v1/dashboard/balance; más en Consumo y facturación .
Cómo reaccionan los clientes más populares
- Claude Code. Muestra el mensaje en la sesión. Tras un 401, Claude Code 2.1.231 y posteriores borra la clave guardada: revisa la clave y la base URL (https://api.oneprovider.dev, sin /v1) y vuelve a configurar la clave. Con el error de saldo se detiene de inmediato: recarga y continúa. Con “prompt is too long” compacta la conversación por sí solo. Los errores temporales 429 y 5xx se reintentan automáticamente.
- Cursor. Muestra el texto del error en el chat. Revisa la clave de API y la base URL https://api.oneprovider.dev/v1 en los ajustes del modelo, recarga si el mensaje habla de saldo y envía de nuevo.
- Codex. Muestra el error de saldo como “Quota exceeded” y se detiene: recarga y ejecuta el comando de nuevo. Los errores temporales los reintenta primero por sí solo.
- Cline. Muestra el error en la tarea con un botón Retry (Reintentar). Corrige primero la clave, la base URL o el saldo y luego pulsa Retry.
- Continue. Muestra el texto del error en el panel del chat. Corrige la causa y envía el mensaje de nuevo.