Erros da API do Claude: 400, 401, 429, 529 e como resolver

Resposta curta

A API do Claude informa cada falha com um JSON que traz um status HTTP e um error.type: 400 invalid_request_error (algo está errado no corpo da requisição), 401 authentication_error (chave ausente ou incorreta), 403 permission_error, 404 not_found_error (caminho ou ID de modelo errado), 413 request_too_large, 429 rate_limit_error, 500 api_error e 529 overloaded_error. Erros 4xx se corrigem mudando a requisição, porque reenviá-la sem alterações falha de novo; 429, 500, 503 e 529 devem ser repetidos com espera exponencial (backoff), respeitando o cabeçalho retry-after quando ele vier. Na APIVAI valem os mesmos códigos, mais o 402 insufficient_quota quando o orçamento de uma chave acaba, e o limite padrão é de 60 requisições por minuto por chave. A maioria dos 404 vem da URL base: use https://api.apivai.com para o formato da Anthropic e https://api.apivai.com/v1 para o formato da OpenAI.

Como é uma resposta de erro da API do Claude?

A API da Anthropic retorna erros em JSON com um objeto error de nível superior que sempre tem type e message, como descreve a página oficial de erros da API do Claude. A APIVAI responde no mesmo formato:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Not found. Check the model name and the endpoint path."
  }
}

O formato da OpenAI (POST /v1/chat/completions e /v1/responses) tradicionalmente usa {"error": {"message": "...", "type": "...", "param": null, "code": "..."}}. Na APIVAI, os erros desses endpoints usam o mesmo corpo mostrado acima. Os SDKs e ferramentas da OpenAI leem error.message e error.type, que estão sempre presentes; em erros 400, 404 e 413 o corpo também pode trazer code e param quando eles indicam qual campo falhou.

Leia sempre error.message primeiro. Em problemas da requisição (400, 404, 413), ele costuma citar o campo ou o modelo exato que causou o erro.

O que significam os códigos de erro da API do Claude?

HTTP	error.type	O que significa	O que fazer	Repetir?
400	`invalid_request_error`	Corpo ou parâmetros inválidos	Corrigir o campo citado na mensagem	Não
401	`authentication_error`	Chave ausente ou inválida	Verificar a chave e o cabeçalho	Não
402	`insufficient_quota`	Orçamento da chave esgotado (APIVAI)	Adicionar orçamento à chave no Dashboard	Não
403	`permission_error`	Conta desativada ou recurso não permitido	Falar com o suporte	Não
404	`not_found_error`	Caminho, URL base ou ID de modelo errado	Verificar o `/v1` e o ID do modelo	Não
413	`request_too_large`	Corpo da requisição grande demais	Enviar menos dados	Não
429	`rate_limit_error`	Requisições demais por minuto ou orçamento da chave esgotado	Aguardar; ler a mensagem	Sim, com backoff
500	`api_error`	Erro inesperado no servidor	Repetir com backoff	Sim
503 / 529	`overloaded_error`	Sobrecarga temporária	Repetir com backoff	Sim

A lista oficial da Anthropic também traz 402 billing_error (um problema de pagamento em uma conta da Anthropic), 409 conflict_error e 504 timeout_error. Para gerações longas, a recomendação oficial contra timeouts é usar streaming. Na APIVAI, o 402 sempre significa que o orçamento da chave em uso acabou.

Por que recebo 401 "invalid x-api-key" ou "Invalid API key"?

Um 401 authentication_error significa que a requisição chegou à API, mas a chave não foi aceita. A APIVAI retorna "Missing API key." quando nenhuma chave foi enviada e "Invalid API key." quando a chave não é sua.

Verifique nesta ordem:

O cabeçalho. O formato da Anthropic normalmente envia x-api-key: <key> e o da OpenAI envia Authorization: Bearer <key>. A APIVAI aceita qualquer um dos dois nos dois formatos, então aqui um 401 diz respeito à chave em si, não ao cabeçalho escolhido.
O texto da chave. Copie de novo no Dashboard; é comum faltar um caractere ou colar espaços ou aspas junto.
Outra chave está sendo enviada. Uma variável de ambiente antiga ANTHROPIC_API_KEY ou OPENAI_API_KEY pode prevalecer sobre a chave digitada nas configurações da ferramenta. O guia de configuração do Claude Code explica quais variáveis o Claude Code lê.
A chave foi excluída ou regenerada. Uma chave regenerada substitui a antiga; atualize todas as ferramentas que a usavam.

Um 403 permission_error com "This account is disabled. Contact support." significa que a chave é válida, mas a conta está desativada; trocar a chave não resolve, então escreva para o suporte.

Como resolver 429 rate_limit_error e 402 insufficient_quota?

Na APIVAI, cada chave tem dois limites:

Uma taxa de requisições. O padrão é 60 requisições por minuto por chave. Agentes que disparam muitas chamadas em paralelo podem ultrapassá-la. Reduza a concorrência, repita com backoff ou peça ao suporte para aumentar o limite.
Um orçamento. Cada chave tem seu próprio orçamento, retirado do saldo da conta quando você cria a chave ou adiciona orçamento a ela. Quando ele acaba, as requisições falham com 402 insufficient_quota ("This key has no budget left. Add budget to the key in the dashboard.") ou com um 429 cuja mensagem diz que o orçamento da chave acabou.

Erros de orçamento não somem com novas tentativas. Abra o Dashboard e adicione orçamento a essa chave. Se o saldo da conta também estiver zerado, recarregue primeiro (a partir de $10). Seu saldo pode ter dinheiro enquanto uma chave específica não tem: para as requisições dela, vale o orçamento próprio da chave. Os preços atuais por token estão na página de preços.

O que é overloaded_error (529) e como devo repetir?

overloaded_error significa que o serviço está temporariamente sobrecarregado. Não é causado pela sua requisição, e a mesma requisição costuma funcionar pouco depois. A APIVAI o retorna como 529, ou como 503 com o mesmo tipo overloaded_error. O 500 api_error é tratado da mesma forma.

O padrão certo é a espera exponencial: aguarde cerca de 1 s, depois 2 s, 4 s, 8 s, acrescente uma pequena variação aleatória (jitter) e pare depois de algumas tentativas. Se a resposta tiver o cabeçalho retry-after, espere pelo menos esse tempo; a APIVAI repassa retry-after e retry-after-ms quando eles vêm definidos.

Os SDKs oficiais da Anthropic já fazem isso: por padrão repetem duas vezes erros de conexão, 429 e respostas 5xx com espera exponencial e respeitam retry-after. Basta aumentar max_retries:

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.apivai.com",
    api_key="YOUR_APIVAI_KEY",
    max_retries=5,  # default is 2
)

try:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        messages=[{"role": "user", "content": "Hello"}],
    )
    print("".join(b.text for b in msg.content if b.type == "text"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.response.headers.get("request-id"), e.message)

Sem SDK, um pequeno laço basta. Ele repete só os códigos temporários e para quando um 429 é sobre orçamento:

import random, time, requests

RETRY = {429, 500, 503, 529}

def post_with_backoff(url, headers, body, attempts=5):
    for i in range(attempts):
        r = requests.post(url, headers=headers, json=body, timeout=600)
        if r.status_code not in RETRY or "budget" in r.text:
            return r
        wait = float(r.headers.get("retry-after", 2 ** i))
        time.sleep(wait + random.random())
    return r

Por que recebo 404 not_found_error?

Quase sempre é a URL base ou o ID do modelo:

Formato da Anthropic: URL base https://api.apivai.com, sem /v1. O SDK da Anthropic e o Claude Code acrescentam /v1/messages sozinhos, então https://api.apivai.com/v1 vira /v1/v1/messages e falha.
Formato da OpenAI: URL base https://api.apivai.com/v1, com um único /v1. Sem ele, a requisição vai para /chat/completions e a APIVAI responde "Unknown endpoint".
Host errado: requisições enviadas para apivai.com em vez de api.apivai.com recebem um 404 cuja mensagem diz "Wrong base URL" e lista os dois endereços corretos.
ID do modelo: use um ID exato como claude-sonnet-4-6, não o nome de exibição. Liste os IDs que sua chave pode usar:

curl https://api.apivai.com/v1/models \
  -H "Authorization: Bearer YOUR_APIVAI_KEY"

Os modelos Claude funcionam nos dois formatos; modelos GPT como o gpt-5.5, só no formato da OpenAI. Mais sobre cada formato: proxy da API do Claude e API compatível com OpenAI.

Por que acontece um 400 invalid_request_error?

Um 400 significa que a API entendeu a requisição, mas recusou o conteúdo. A mensagem diz qual é o problema. Os mais frequentes:

Falta max_tokens em uma requisição no formato da Anthropic (lá ele é obrigatório).
A conversa termina com uma mensagem do assistente (prefill). Os modelos Claude 4.6 e posteriores recusam isso; termine com uma mensagem do usuário.
Uma configuração antiga de thinking: modelos mais novos, como o claude-opus-5-5, recusam thinking: {"type": "enabled"} e esperam adaptive thinking. Remova o campo thinking para usar o padrão.
Blocos de thinking editados ou removidos antes de serem reenviados em um laço com ferramentas. Devolva-os exatamente como chegaram.

Um problema parecido nem é erro: respostas vazias ou cortadas. O thinking vem ativado por padrão e seus tokens contam como saída, então um max_tokens pequeno pode acabar antes de aparecer qualquer texto. A resposta termina com stop_reason: "max_tokens" (ou finish_reason: "length" no formato da OpenAI). Aumente max_tokens para 4096 ou mais.

413 request_too_large significa que o próprio corpo é grande demais. O limite da Anthropic para a Messages API é de 32 MB. As causas comuns são arquivos grandes em base64 e históricos muito longos: envie menos arquivos ou arquivos menores, ou corte os turnos antigos.

Como os erros aparecem em uma resposta com streaming?

Com "stream": true, o status HTTP é 200 assim que o fluxo começa, então uma falha posterior não pode mais mudá-lo. Em vez disso, ela chega como um evento dentro do fluxo. A documentação de streaming da Anthropic traz este exemplo:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Se um fluxo pela APIVAI parar antes de terminar, a APIVAI envia um event: error com api_error e "The response was interrupted. Please retry." em vez de encerrar em silêncio, de modo que os SDKs lançam uma exceção em vez de devolver meia resposta. Trate como um 500: repita a requisição inteira.

Como encontro o request ID?

As respostas podem trazer um cabeçalho request-id (alguns serviços usam x-request-id); a APIVAI o repassa sempre que ele existe. Mostre os cabeçalhos com curl:

curl -sS -D - https://api.apivai.com/v1/messages \
  -H "x-api-key: YOUR_APIVAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hi"}]}'

No SDK de Python, uma resposta bem-sucedida tem msg._request_id e uma exceção tem e.response.headers. Informe o ID, o horário e a mensagem de erro ao falar com o suporte.

Quais são as causas mais comuns, num relance?

Sintoma	Causa provável	Solução
404 em toda requisição	`/v1` ausente, sobrando ou duplicado	Anthropic: `https://api.apivai.com`; OpenAI: `https://api.apivai.com/v1`
401 com uma chave que parece certa	Uma variável de ambiente antiga envia outra chave	Removê-la ou trocá-la pela chave da APIVAI
404 ou 400 citando o modelo	Erro de digitação ou nome de exibição	Copiar o ID de `GET /v1/models`
Respostas vazias ou cortadas	`max_tokens` baixo demais com thinking	4096 ou mais
413	Arquivos grandes no corpo	Enviar menos dados
429 durante execuções de agentes	Mais de 60 requisições por minuto	Reduzir a concorrência, backoff
402, ou 429 sobre orçamento	Orçamento da chave esgotado	Adicionar orçamento à chave
529 / 503	Sobrecarga temporária	Repetir com backoff

As configurações de cada ferramenta estão na documentação e em guias como Cline com Claude e GPT.

Perguntas frequentes

Devo repetir um erro 400 ou 401?

Não. Erros 4xx diferentes de 429 descrevem um problema na requisição ou na chave, e a mesma requisição falha do mesmo jeito. Corrija a causa primeiro.

Qual a diferença entre 429 e 529?

O 429 tem a ver com os seus próprios limites: requisições por minuto e, na APIVAI, também o orçamento da chave. O 529 overloaded_error é uma sobrecarga temporária que não depende do seu uso; tanto o 429 por taxa quanto o 529 são repetidos com backoff.

O SDK da Anthropic repete automaticamente?

Sim. Por padrão ele repete duas vezes erros de conexão, 429 e respostas 5xx com espera exponencial e respeita retry-after. Defina max_retries no cliente para mudar isso, ou 0 para desativar.

Por que a resposta volta vazia sem nenhum erro?

O thinking consumiu todo o max_tokens antes do texto visível. Aumente max_tokens para 4096 ou mais; os tokens de thinking são cobrados como tokens de saída.

Minha conta tem saldo, por que recebo 402?

O saldo e o orçamento da chave são coisas diferentes. Cada chave gasta só o próprio orçamento; adicione orçamento a essa chave no Dashboard.

Crie uma conta, recarregue a partir de $10 e crie uma chave para chamar o Claude e o GPT com uma única API.