Guides
Error codes
Decode every OneProvider error: what each status code means, the exact message, time limits, errors mid-stream and when it is safe to retry.
What each status code means, the exact message you will see, and what to do next.
All models, capabilities, and prices Documentation index for AI agents:https://oneprovider.dev/docs/llms.txt Error shape
Every error is JSON of the same shape on every endpoint (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). The balance error also carries code:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}OpenAI SDKs read error.message from this body as usual, so you see the same text in any client.
Status codes
| Status | error.type | Message and meaning | What to do |
|---|---|---|---|
| 400 | invalid_request_error | The request is malformed: invalid JSON, a missing field, or a value that is not allowed. The message names the problem. | Fix what the message points to and resend. Sending it again unchanged returns the same error. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum The input is larger than this model's context window. N and M depend on the model. | Shorten the history or attachments, or pick a model with a larger context. Claude Code compacts the conversation on its own when it sees this. |
| 400 | invalid_request_error | Model X is not available on this API key Your key's plan does not include this model. | Pick a model listed by GET /v1/models or on the pricing page. |
| 401 | authentication_error | Invalid API key API key is required The key is missing, mistyped, or sent in the wrong header. | Send the raw sk-… key, without quotes or spaces, in x-api-key or Authorization: Bearer. |
| 401 | authentication_error | API key is disabled The key is disabled or the account is inactive. | Check the key in your cabinet (Keys page) or message @Oneproviderhelpbot. |
| 403 | permission_error | API key expired The key is past its expiry date. | Renew the key or issue a new one in your cabinet (Keys page). |
| 404 | not_found_error | The requested API endpoint does not exist Usually a wrong base URL, for example /v1/v1 in the path. | Claude Code and Anthropic SDKs: https://api.oneprovider.dev. OpenAI SDKs and OpenAI-compatible clients: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit The request body is larger than 32 MB. | Send smaller or fewer images and files, or split the work into several requests. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev The cabinet balance or the key's spend limit is used up. The body carries error.code insufficient_quota and the response has the header x-should-retry: false. | Do not retry. Top up the cabinet (bot or app.oneprovider.dev) or raise the key's limit, then send the request again. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Too many requests in a short time. May include a Retry-After header. | Wait Retry-After seconds when present, otherwise retry with a growing pause. If it keeps happening, send fewer requests in parallel. |
| 500, 502 | server_error | Service temporarily unavailable; retry later A temporary failure on our side. | Retry with a growing pause. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Temporary. Nothing is wrong with your key or your request. | Retry with a growing pause; it usually clears within a minute. |
| 504 | server_error | Service timed out; retry later The request ran past a time limit (see below). | Retry. For long answers turn on stream: true. |
Time limits
- A non-streaming request must start answering within 6 minutes.
- Any request, streaming included, is capped at 10 minutes.
- For long generations use
stream: true: a stream starts answering right away. If one answer needs more than 10 minutes, split the task.
Errors inside a stream
Once a stream has started, the status is already 200, so the error arrives as an event. The Messages API sends an event: error frame with the same error body; the Responses API sends a response.failed event with the reason in response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Handle it like the matching status code. The partial answer is incomplete: if the error is retryable, send the whole request again.
When to retry
- Fix first, do not retry: 400, 401, 403, 404, 413, and 429 with
insufficient_balance. The same request fails the same way until you change the request, the key, or the balance. - Retry with a growing pause: 429
rate_limit_error, 500, 502, 503, 504. For example 1 s, 2 s, 4 s and on up to a minute, with a little random jitter. IfRetry-Afteris present, wait at least that long. - Respect
x-should-retry: false. The official Anthropic and OpenAI SDKs already do, so they do not retry the balance error. - Check what is left with
GET /v1/dashboard/balance, see Usage & billing .
How popular clients react
- Claude Code. Shows the message in the session. After a 401, Claude Code 2.1.231 and newer removes the saved key: check the key and the base URL (https://api.oneprovider.dev, without /v1), then set the key again. On the balance error it stops at once: top up and continue. On "prompt is too long" it compacts the conversation by itself. Temporary 429 and 5xx errors are retried automatically.
- Cursor. Shows the error text in the chat. Check the API key and the base URL https://api.oneprovider.dev/v1 in the model settings, top up if the message is about balance, then send again.
- Codex. Shows the balance error as "Quota exceeded" and stops: top up and run the command again. Temporary errors are retried on its own first.
- Cline. Shows the error in the task with a Retry button. Fix the key, base URL, or balance first, then press Retry.
- Continue. Shows the error text in the chat panel. Fix the cause and send the message again.