API key não funciona? Resolva os erros 401, 402, 403 e 429
Por que uma API key de IA para de funcionar: o que são os erros 401, 402, 403 e 429, que código cada provedor usa para saldo zerado e como resolver.
- Quando uma API key (chave de API) de IA "não funciona", o número do erro diz o motivo: 401 quer dizer que a chave em si está errada, 402 geralmente quer dizer que o saldo ou os créditos acabaram, 403 quer dizer que a chave não tem permissão para aquilo, e 429 quer dizer solicitações demais ou, em alguns provedores, saldo zerado.
- Os provedores não usam o mesmo código para saldo zerado. DeepSeek, OpenRouter, Mistral, Together, Fireworks e a cobrança pré-paga do Gemini usam 402; OpenAI, Kimi e Z.ai usam 429; o Qwen, da Alibaba Cloud, usa 403. Leia a mensagem, não só o número.
- Erros de saldo não somem se você esperar; limites de taxa geralmente somem. A tabela abaixo traz a página oficial de erros de cada provedor, conferida em 18 de novembro de 2026.

O que "API key não funciona" quer dizer na prática?
A API key é o código secreto que um app envia em cada solicitação para o provedor de IA saber que é você e em qual conta cobrar. Quando algo dá errado, o provedor responde com um erro: um número de três dígitos chamado código de status HTTP, mais uma mensagem curta.
O número diz que tipo de problema é; a mensagem dá o detalhe. O Oriveo transforma os erros mais comuns em títulos simples, como "Chave de API inválida" ou "Cota do provedor esgotada", explicados mais abaixo nesta página.
Guia rápido: 401, 402, 403, 429 e 5xx
Comece por aqui. Encontre o seu número e depois leia a seção correspondente abaixo. Este resumo segue as páginas de erro da OpenAI, da Anthropic e de outros provedores em 18 de novembro de 2026.
| Código | O que costuma significar | Esperar resolve? | O que fazer |
|---|---|---|---|
| 401 | A chave está errada: falta um caractere, sobrou um espaço, a chave foi apagada ou é de outro provedor ou região | Não | Copie a chave de novo ou crie uma nova; confira o provedor e a região |
| 402 | Pagamento necessário: o saldo pré-pago ou os créditos acabaram, ou há um problema na cobrança | Não | Recarregue, ou corrija a forma de pagamento na página de cobrança do provedor |
| 403 | A chave funciona, mas não tem permissão: país ou região não atendidos, sem acesso àquele modelo ou falta uma etapa de verificação | Não | Confira as regiões atendidas, as permissões da chave e qualquer verificação pendente |
| 404 | O nome do modelo ou o endereço está errado | Não | Escolha outro modelo ou confira o endereço |
| 429 | Solicitações demais em pouco tempo ou, em alguns provedores, saldo zerado ou limite de gasto atingido | Muitas vezes, se for limite de taxa | Espere e tente de novo; se a mensagem falar em quota, balance, credit ou spend limit, recarregue ou aumente o limite |
| 500–504, 529 | Falha ou sobrecarga do lado do provedor | Geralmente | Tente mais tarde ou troque de modelo |
Por que aparece saldo insuficiente ou cota esgotada?
A maioria dos provedores exige crédito pré-pago ou uma forma de cobrança ativa antes de a API funcionar, e cada um avisa do saldo zerado do seu jeito. Uma chave nova não resolve nenhum desses casos; adicionar crédito resolve.
Este é o código que cada um dos 15 provedores integrados do Oriveo documenta quando o saldo ou o crédito acaba. "Não informado" quer dizer que a documentação do provedor, conferida em 18 de novembro de 2026, não dá um código HTTP para esse caso.
| Provedor | Código quando o saldo acaba | O que a mensagem diz | Página oficial |
|---|---|---|---|
| OpenAI | 429 | credit_balance_exhausted (o tipo do erro ainda pode aparecer como insufficient_quota) | developers.openai.com/api/docs/guides/error-codes |
| Anthropic (Claude) | Não informado | "Your credit balance is too low to access the Anthropic API"; problemas de pagamento retornam 402 billing_error | platform.claude.com/docs/en/api/errors (códigos); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (mensagem) |
| Google Gemini | 402 (cobrança pré-paga) | payment_required; o 403 também pode indicar saldo em aberto no Cloud Billing | aistudio.google.com/docs/api-errors |
| OpenRouter | 402 | A sua conta ou API key não tem créditos suficientes | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI (Grok) | Não informado | As solicitações são recusadas quando os créditos pré-pagos acabam | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | Não documentado | O Groq cobra depois do uso; a página de erros dele não lista erro de saldo | console.groq.com/docs/errors |
| Together AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | Não informado (código de negócio 1008) | insufficient balance | platform.minimax.io/docs/api-reference/errorcode |
| Z.ai (GLM) | 429 (código 1113) | Insufficient balance or no resource package. Please recharge. | docs.z.ai/api-reference/api-code |
| Qwen (Alibaba Cloud) | 403 | Arrearage ou isv.OUT_OF_SERVICE (conta com pagamento em atraso) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi (Moonshot AI) | 429 | exceeded_current_quota_error | platform.kimi.ai/docs/api/errors |
| SiliconFlow | Não documentado | Nenhum erro de saldo listado | docs.siliconflow.com/en/faqs/error-code |
401: API key inválida ou falha de autenticação
Um 401 quer dizer que o provedor não reconhece a chave. Mensagens típicas: "Incorrect API key provided" (OpenAI), "authentication_error" (Anthropic), "Authentication Fails" (DeepSeek) e "Invalid API key: this is not an OpenRouter API key" (OpenRouter).
- Copie a chave de novo no site do provedor e confira se não faltou nenhum caractere nem sobrou espaço no começo ou no fim.
- Confirme que a chave é do provedor que você escolheu. Uma chave da OpenAI não funciona como chave do OpenRouter, e vice-versa.
- Kimi, MiniMax e Qwen têm plataformas regionais separadas, e a chave de uma não funciona na outra. No Oriveo, escolha a região certa no seletor "Endpoint oficial" ("URL de solicitação oficial" no iPhone).
- Se a chave foi apagada, revogada ou expirou, crie uma nova.
402: pagamento necessário ou saldo insuficiente
Um 402 é questão de dinheiro: o saldo pré-pago zerou ou a forma de pagamento falhou. Recarregue ou atualize os seus dados de pagamento na página de cobrança do provedor e envie de novo. Esperar não ajuda.
No Oriveo, isso aparece como "Cota do provedor esgotada": "O provedor informa que a cota ou o crédito desta chave de API acabou. Verifique sua cobrança com o provedor ou troque de modelo."
403: acesso proibido ou permissão negada
Um 403 quer dizer que o provedor reconheceu a chave, mas não permite a solicitação. O motivo depende do provedor:
- A OpenAI retorna "Country, region, or territory not supported" quando a API é usada a partir de um país que ela não atende. Cada provedor publica a sua lista de países atendidos.
- O Gemini retorna 403 quando um projeto do nível gratuito precisa de verificação (FREE_TIER_VERIFICATION_REQUIRED), quando a conta do Cloud Billing vinculada tem saldo em aberto ou quando o Google bloqueou uma chave denunciada como vazada.
- A Anthropic retorna permission_error quando a chave não pode usar o recurso; confira as configurações da sua organização e do workspace.
- O OpenRouter retorna 403 quando uma solicitação é bloqueada por permissões, moderação, uma regra de proteção (guardrail) ou um limite de orçamento.
- O SiliconFlow exige verificação de identidade para alguns modelos.
- O Qwen usa 403 para conta com pagamento em atraso e para AllocationQuota.FreeTierOnly, quando a cota gratuita acabou e a opção "Free Quota Only" está ativada.
429: solicitações demais, limite de taxa ou cota excedida
Na maioria das vezes, 429 quer dizer que você enviou solicitações ou tokens demais em pouco tempo. Isso é um limite de taxa (rate limit), e ele passa se você esperar algumas dezenas de segundos. Se a resposta trouxer um tempo em Retry-After, espere esse tempo.
Vários provedores também usam 429 para saldo zerado ou limite de gasto, e aí esperar não resolve: OpenAI (credit_balance_exhausted, ou um limite de gasto definido por você), Kimi (exceeded_current_quota_error), Z.ai (código 1113) e Anthropic, quando uma organização atinge o limite mensal de gasto (enforced_spend_limit_reached), que vale até o mês seguinte, a menos que você peça um nível de uso mais alto.
Os níveis gratuitos são mais apertados. O nível gratuito do Gemini e os modelos grátis do OpenRouter têm limites por minuto e por dia.
No Oriveo, um limite de taxa aparece como "Limite de taxa" na web ou "Limite de taxa do provedor" no iPhone e no Android. Se a mensagem falar de cota ou crédito, o Oriveo mostra "Cota do provedor esgotada".
O que significam as mensagens de erro do Oriveo?
Estas são as mensagens que podem aparecer no Oriveo, com o texto que o app mostra em português:
| O que o Oriveo mostra | O que significa | O que fazer |
|---|---|---|
| Salvo, mas a chave parece inválida. Você pode verificá-la mais tarde nas configurações do provedor. | O Oriveo salvou o provedor, mas o provedor recusou a chave na verificação | Copie a chave de novo e atualize nas configurações desse provedor |
| Chave de API inválida (na web: API Key inválida) | O provedor retornou 401 ou 403 | Confira ou troque a chave; no caso de 403, confira a região e as permissões |
| Cota do provedor esgotada | O provedor informa que o crédito ou a cota desta chave acabou (402, ou 429 falando de cota) | Recarregue no provedor ou troque para outro modelo |
| Limite de taxa / Limite de taxa do provedor | Solicitações demais por enquanto (429) | Espere um pouco e tente de novo |
| Cota gratuita esgotada (no Android: Cota gratuita atingida) | A cota de hoje do Oriveo Free acabou; isso não tem nada a ver com a sua chave | Adicione a sua própria API key ou espere a renovação às 00:00 UTC |

Usa um endpoint personalizado, relay ou gateway?
Se você se conecta por um endpoint personalizado, o erro pode vir desse serviço ou do provedor que está por trás dele. Quando o Oriveo diz "Esta conexão não conseguiu alcançar o provedor upstream", a conta que o próprio serviço tem no provedor pode estar inválida, sem créditos ou com o limite de taxa atingido. Não é problema da sua configuração; troque para outra conexão ou fale com quem administra o serviço.
Confira isto antes de criar uma chave nova
Uma chave nova resolve o 401 e quase nada além disso. Passe por esta lista primeiro:
- Você escolheu o provedor certo e, no caso de Kimi, MiniMax, Qwen, SiliconFlow e Z.ai, a região certa.
- Você copiou a chave inteira, sem espaços.
- Há crédito na conta ou uma forma de cobrança ativa.
- O seu país ou região está na lista de atendidos do provedor.
- O modelo escolhido está disponível para a sua conta ou o seu nível.
Dúvidas comuns sobre o app
Por que a minha API key não funciona?
O que significa o erro 401 em uma API key?
O que é o erro 402 Payment Required?
O erro 429 é limite de taxa ou falta de cota?
Por que a minha API key da OpenAI diz insufficient_quota?
Por que a minha API key nova não funciona se copiei certinho?
Leituras relacionadas
Do nosso blog
Erros explicados em linguagem simples, para todas as suas chaves
Abra o app web ou baixe o Oriveo para iPhone ou Android, adicione chaves de 15 provedores e saiba com clareza por que uma solicitação falhou.
Ainda não tem uma chave de API? Comece com o Oriveo Free.