Erros de API key

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.

Atualizado em
  • 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.
Oriveo no iPhone: a tela de provedores, com os provedores que você conectou e o gasto deste mês.

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.

Guia rápido: 401, 402, 403, 429 e 5xx
CódigoO que costuma significarEsperar resolve?O que fazer
401A chave está errada: falta um caractere, sobrou um espaço, a chave foi apagada ou é de outro provedor ou regiãoNãoCopie a chave de novo ou crie uma nova; confira o provedor e a região
402Pagamento necessário: o saldo pré-pago ou os créditos acabaram, ou há um problema na cobrançaNãoRecarregue, ou corrija a forma de pagamento na página de cobrança do provedor
403A 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çãoNãoConfira as regiões atendidas, as permissões da chave e qualquer verificação pendente
404O nome do modelo ou o endereço está erradoNãoEscolha outro modelo ou confira o endereço
429Solicitações demais em pouco tempo ou, em alguns provedores, saldo zerado ou limite de gasto atingidoMuitas vezes, se for limite de taxaEspere e tente de novo; se a mensagem falar em quota, balance, credit ou spend limit, recarregue ou aumente o limite
500–504, 529Falha ou sobrecarga do lado do provedorGeralmenteTente 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.

Por que aparece saldo insuficiente ou cota esgotada?
ProvedorCódigo quando o saldo acabaO que a mensagem dizPágina oficial
OpenAI429credit_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_errorplatform.claude.com/docs/en/api/errors (códigos); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (mensagem)
Google Gemini402 (cobrança pré-paga)payment_required; o 403 também pode indicar saldo em aberto no Cloud Billingaistudio.google.com/docs/api-errors
OpenRouter402A sua conta ou API key não tem créditos suficientesopenrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)Não informadoAs solicitações são recusadas quando os créditos pré-pagos acabamdocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
GroqNão documentadoO Groq cobra depois do uso; a página de erros dele não lista erro de saldoconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxNão informado (código de negócio 1008)insufficient balanceplatform.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)403Arrearage ou isv.OUT_OF_SERVICE (conta com pagamento em atraso)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlowNão documentadoNenhum erro de saldo listadodocs.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 significam as mensagens de erro do Oriveo?
O que o Oriveo mostraO que significaO 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çãoCopie 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 403Confira ou troque a chave; no caso de 403, confira a região e as permissões
Cota do provedor esgotadaO 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 provedorSolicitaçõ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 chaveAdicione a sua própria API key ou espere a renovação às 00:00 UTC
Tela Provedores do Oriveo com provedores conectados, como OpenAI, Z.ai, Groq, Gemini e Anthropic, cada um com o seu gasto
Abra um provedor desta lista para conferir ou trocar a chave.

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?
Veja o número do erro. 401 quer dizer que a chave está errada; 402, que o saldo ou os créditos acabaram; 403, que a solicitação não é permitida (muitas vezes por região ou permissões); e 429, que houve solicitações demais ou, em alguns provedores, que o saldo zerou.
O que significa o erro 401 em uma API key?
O provedor não reconhece a chave. Copie de novo sem espaços, confira se ela é do provedor e da região que você escolheu, ou crie uma chave nova.
O que é o erro 402 Payment Required?
O seu saldo pré-pago ou os seus créditos acabaram, ou há um problema no pagamento. DeepSeek, OpenRouter, Mistral, Together, Fireworks e a cobrança pré-paga do Gemini usam esse código. Recarregue na página de cobrança do provedor; esperar não resolve.
O erro 429 é limite de taxa ou falta de cota?
Pode ser qualquer um dos dois. Geralmente é um limite de taxa que passa depois de uma pequena espera. Mas OpenAI, Kimi e Z.ai também retornam 429 quando o saldo está zerado, então, se a mensagem falar de quota, balance ou credit, adicione crédito em vez de esperar.
Por que a minha API key da OpenAI diz insufficient_quota?
A sua conta de API da OpenAI ficou sem crédito pré-pago. A OpenAI retorna 429 com o código credit_balance_exhausted, e o tipo do erro ainda pode dizer insufficient_quota. Adicione crédito nas configurações de cobrança da OpenAI; uma chave nova não ajuda.
Por que a minha API key nova não funciona se copiei certinho?
Geralmente porque a conta ainda não tem crédito ou a cobrança não foi configurada, porque a chave é de outra região, ou porque a API não é oferecida no seu país. Confira isso antes de criar outra chave.

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.