Códigos de erro
Decifre os erros da OneProvider: o que significa cada código de status, a mensagem, limites de tempo, erros no meio do stream e quando tentar de novo.
O que significa cada código de status, a mensagem exata que você verá e o que fazer em seguida.
Todos os modelos, recursos e preços Índice da documentação para agentes de IA:https://oneprovider.dev/docs/llms.txt Formato do erro
Todo erro é um JSON do mesmo formato em todos os endpoints (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). O erro de saldo traz também code:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}Os SDKs da OpenAI leem error.message deste corpo como de costume, então você vê o mesmo texto em qualquer cliente.
Códigos de status
| Status | error.type | Mensagem e significado | O que fazer |
|---|---|---|---|
| 400 | invalid_request_error | A requisição está malformada: JSON inválido, campo ausente ou valor não permitido. A mensagem indica o problema. | Corrija o que a mensagem aponta e envie de novo. Reenviar sem alterações retorna o mesmo erro. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum A entrada é maior que a janela de contexto deste modelo. N e M dependem do modelo. | Reduza o histórico ou os anexos, ou escolha um modelo com contexto maior. O Claude Code compacta a conversa sozinho quando vê isso. |
| 400 | invalid_request_error | Model X is not available on this API key O plano da sua chave não inclui este modelo. | Escolha um modelo listado em GET /v1/models ou na página de preços. |
| 401 | authentication_error | Invalid API key API key is required A chave está ausente, foi digitada errado ou enviada no cabeçalho errado. | Envie a chave sk-… pura, sem aspas nem espaços, em x-api-key ou Authorization: Bearer. |
| 401 | authentication_error | API key is disabled A chave está desativada ou a conta está inativa. | Confira a chave no seu painel (página Chaves) ou escreva para @Oneproviderhelpbot. |
| 403 | permission_error | API key expired A chave passou da data de expiração. | Renove a chave ou emita uma nova no seu painel (página Chaves). |
| 404 | not_found_error | The requested API endpoint does not exist Em geral, uma base URL errada, por exemplo /v1/v1 no caminho. | Claude Code e SDKs da Anthropic: https://api.oneprovider.dev. SDKs da OpenAI e clientes compatíveis com a OpenAI: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit O corpo da requisição é maior que 32 MB. | Envie imagens e arquivos menores ou em menor número, ou divida o trabalho em várias requisições. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev O saldo do painel ou o limite de gastos da chave acabou. O corpo traz error.code insufficient_quota e a resposta tem o cabeçalho x-should-retry: false. | Não tente de novo. Recarregue o painel (bot ou app.oneprovider.dev) ou aumente o limite da chave e depois envie a requisição outra vez. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Requisições demais em pouco tempo. Pode incluir um cabeçalho Retry-After. | Aguarde os segundos de Retry-After, se presente; caso contrário, tente de novo com uma pausa crescente. Se continuar acontecendo, envie menos requisições em paralelo. |
| 500, 502 | server_error | Service temporarily unavailable; retry later Uma falha temporária do nosso lado. | Tente de novo com uma pausa crescente. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Temporário. Não há nada de errado com a sua chave nem com a sua requisição. | Tente de novo com uma pausa crescente; em geral some em até um minuto. |
| 504 | server_error | Service timed out; retry later A requisição passou de um limite de tempo (veja abaixo). | Tente de novo. Para respostas longas, ative stream: true. |
Limites de tempo
- Uma requisição sem streaming deve começar a responder em até 6 minutos.
- Qualquer requisição, inclusive com streaming, tem teto de 10 minutos.
- Para gerações longas, use
stream: true: um stream começa a responder na hora. Se uma resposta precisar de mais de 10 minutos, divida a tarefa.
Erros dentro de um stream
Quando um stream já começou, o status já é 200, então o erro chega como um evento. A Messages API envia um frame event: error com o mesmo corpo de erro; a Responses API envia um evento response.failed com o motivo em response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Trate-o como o código de status correspondente. A resposta parcial está incompleta: se o erro permitir nova tentativa, envie a requisição inteira de novo.
Quando tentar de novo
- Corrija primeiro, não tente de novo: 400, 401, 403, 404, 413 e 429 com
insufficient_balance. A mesma requisição falha do mesmo jeito até você mudar a requisição, a chave ou o saldo. - Tente de novo com uma pausa crescente: 429
rate_limit_error, 500, 502, 503, 504. Por exemplo, 1 s, 2 s, 4 s e assim por diante até um minuto, com um pouco de jitter aleatório. SeRetry-Afterestiver presente, aguarde pelo menos esse tempo. - Respeite
x-should-retry: false. Os SDKs oficiais da Anthropic e da OpenAI já fazem isso, então não fazem novas tentativas no erro de saldo. - Veja quanto resta com
GET /v1/dashboard/balance(consulte Consumo e cobrança ).
Como os clientes populares reagem
- Claude Code. Mostra a mensagem na sessão. Após um 401, o Claude Code 2.1.231 e posteriores removem a chave salva: confira a chave e a base URL (https://api.oneprovider.dev, sem /v1) e defina a chave de novo. No erro de saldo, ele para na hora: recarregue e continue. Em "prompt is too long", ele compacta a conversa sozinho. Em erros temporários 429 e 5xx, ele tenta de novo automaticamente.
- Cursor. Mostra o texto do erro no chat. Confira a chave de API e a base URL https://api.oneprovider.dev/v1 nas configurações do modelo, recarregue se a mensagem for sobre saldo e envie de novo.
- Codex. Mostra o erro de saldo como "Quota exceeded" e para: recarregue e execute o comando de novo. Antes disso, ele mesmo tenta de novo nos erros temporários.
- Cline. Mostra o erro na tarefa, com um botão Retry (Tentar de novo). Corrija primeiro a chave, a base URL ou o saldo e depois clique em Retry.
- Continue. Mostra o texto do erro no painel do chat. Corrija a causa e envie a mensagem de novo.