Source: https://aiprimetech.io/pt/learn/claude-api-errors-troubleshooting/

[Início](/pt/) / [Aprenda](/pt/learn/) / Erros da API do Claude explicados: erro de servidor 500, sobrecarga 529, limite de uso 429, requisição inválida 400 — e a correção para cada um 

# Erros da API Claude explicados: erro de servidor 500, sobrecarga 529, limite de requisições 429, requisição inválida 400 — e a correção para cada um 

Todo desenvolvedor que usa a API do Claude acaba encontrando erros. Alguns são causados por você (requisições malformadas), outros pela Anthropic (problemas no servidor) e outros pela arquitetura (limites de uso durante uso intenso). Este guia aborda todos os códigos de erro comuns da API do Claude, com causas reais, correções concretas e lógica de novas tentativas pronta para produção. Ele também explica como o roteamento por um gateway com várias contas no provedor pode reduzir a frequência de erros de limite de uso e de sobrecarga. 

## Verifique o acesso e o modelo antes de tentar novamente 

Confirme que o acesso pelo seu plano ou saldo está ativo, verifique o grupo de chaves e use um modelo retornado para essa chave. Uma resposta bem-sucedida à listagem de modelos é uma verificação inicial; valide uma pequena requisição de geração antes de executar uma tarefa maior com um agente. 

Use [modelos e grupos de chaves](/pt/docs/getting-started/models/) e a [lista de verificação de configuração do agente](/pt/agents/) para distinguir problemas de acesso de problemas de configuração das ferramentas e erros do provedor. 

## "Erro de servidor do Claude": qual deles você realmente está enfrentando? 

"Erro de servidor do Claude" é o que as pessoas digitam quando a API para de responder, mas o número na mensagem determina o que fazer. Um **500** indica uma falha interna da API — aguarde, tente novamente ou troque de modelo. Um **529** indica que o modelo está saturado para todos — adote as mesmas medidas, e a situação se resolve por conta própria. Um **429** indica que você atingiu um limite — diminua o ritmo ou reduza as requisições paralelas. 

Um **400** significa que a própria requisição foi rejeitada — repetir a mesma requisição causará outra falha. Encontre seu código abaixo; cada seção apresenta a mensagem exata, a causa e a correção. Se o erro aparecer no Claude Code, em vez de no seu próprio código, os guias de erros do Claude Code em /claude-code/errors/ abordam as mensagens específicas da CLI (tempos limite de OAuth, "o processo foi encerrado com o código 1", concorrência no uso de ferramentas). 

## Erro 400 — Requisição inválida 

Um erro 400 significa que sua requisição é estruturalmente inválida. A API do Claude a rejeitou antes mesmo de tentar gerar uma resposta. O corpo do erro contém uma mensagem explicando o problema — sempre leia essa mensagem com atenção. As causas comuns incluem: array messages vazio ou malformado, campo content com valor null em vez de uma string, max_tokens acima do limite do modelo, identificador de modelo inexistente, prompt de sistema no formato errado ou definições de ferramentas com erros de esquema. 

O erro 400 mais frequente entre usuários do Claude Code é o excesso de comprimento do contexto. Quando seu histórico de conversa ultrapassa a janela de contexto do modelo (200K tokens para a maioria dos modelos Claude), a API retorna um 400 com uma mensagem indicando que a entrada é muito longa. A solução é usar /compact para resumir o histórico, remover do contexto o conteúdo de arquivos grandes ou iniciar uma nova sessão. Isso não é um limite de uso — é uma restrição rígida ao tamanho da requisição. 

Outro erro 400 comum ocorre ao enviar um parâmetro ou uma versão de modelo sem suporte. Se você atualizou recentemente seu SDK ou alterou os identificadores de modelo, confira se todos os campos da requisição correspondem à especificação atual da API. Os IDs de modelo diferenciam maiúsculas de minúsculas e são específicos de cada versão — 'claude-opus-4-6' é válido, mas 'Claude-Opus-4.6' não é. Em caso de dúvida, consulte o endpoint /v1/models para ver exatamente quais identificadores o provedor aceita. 

## Erro 400 — "A entrada é muito longa para o modelo solicitado" 

Esse erro 400 específico significa que sua requisição (prompt de sistema + mensagens + quaisquer definições de ferramentas) excede a janela de contexto do modelo. Não se trata de um limite de uso, e tentar novamente não resolverá o problema — o mesmo payload falhará todas as vezes até que você reduza a entrada ou passe para um modelo com uma janela de contexto maior. 

Três correções práticas, em ordem de esforço: primeiro, reduza o histórico de conversa que você reenvia — a maioria dos aplicativos de chat precisa apenas das últimas interações e de um resumo atualizado, não da transcrição completa. Segundo, conte os tokens antes do envio (o endpoint de contagem de tokens é gratuito) e imponha um limite rígido de entrada no código. Terceiro, se você realmente precisar do contexto completo — repositórios inteiros, documentos do tamanho de livros — mude para um modelo com contexto de 1M, como Fable 5, no qual a mesma requisição cabe com folga. 

Uma armadilha comum em ferramentas com agentes: sessões prolongadas acumulam resultados de ferramentas e conteúdo de arquivos até que mais uma interação faça a requisição ultrapassar o limite. Se o erro aparecer no meio de uma sessão no Claude Code ou em um agente semelhante, compacte ou limpe o contexto da sessão em vez de reduzir seu prompt. 

## Erro 429 — "Limite de uso atingido" / "Limite de uso excedido" 

A mesma condição aparece com duas formulações. A API retorna HTTP 429 com rate_limit_error; claude.ai e Claude Code exibem a mensagem como "limite de uso excedido" ou "limite de uso atingido". Independentemente do texto exibido, a causa é a mesma: sua conta consumiu a cota da janela atual, e as requisições estão sendo recusadas até que ela seja renovada. 

Um 429 significa que você excedeu a taxa de requisições permitida. A resposta inclui um cabeçalho Retry-After que informa quantos segundos aguardar antes de tentar novamente. Os limites de uso da Anthropic operam em várias dimensões: requisições por minuto (RPM), tokens por minuto (TPM) e tokens por dia (TPD). Atingir qualquer um desses limites gera um 429. A mensagem de erro geralmente indica qual limite foi atingido. 

Para usuários do Claude Code, os limites de uso são o erro mais frustrante porque interrompem o fluxo de trabalho. Um único desenvolvedor executando o Claude Code com subagentes pode facilmente atingir os limites de RPM durante operações paralelas ou os limites de TPM durante sessões com arquivos grandes no contexto. Os limites variam conforme o nível da conta — os níveis inferiores têm limites mais restritos, que o uso intenso de agentes ultrapassa com frequência. 

A resposta correta a um 429 é usar espera exponencial com variação aleatória. Aguarde o intervalo indicado por Retry-After e adicione um atraso aleatório para evitar uma avalanche de requisições caso vários clientes atinjam o limite simultaneamente. Um gateway como o AI Prime Tech Unlimited ajuda a reduzir erros 429 ao encaminhar requisições por várias contas de provedores upstream, multiplicando efetivamente a cota disponível de limites de requisições. Quando uma conta upstream atinge o limite, o gateway encaminha a requisição para outra. 

## Erro 500 — Erro interno do servidor 

Um erro 500 significa que algo deu errado no servidor — não é culpa sua, nem algo que você possa corrigir alterando sua requisição. Esses erros são transitórios: a mesma requisição que falhou com um 500 provavelmente terá sucesso se você tentar novamente após um breve intervalo. A infraestrutura da Anthropic ocasionalmente retorna erros 500 durante implantações, alterações de capacidade ou interrupções de serviços internos. 

O tratamento correto para erros 500 é simplesmente tentar novamente com intervalos de espera progressivos. Aguarde 1-2 segundos e repita exatamente a mesma requisição. Se ela falhar novamente, aguarde 4 segundos, depois 8, até um máximo de aproximadamente 60 segundos. A maioria dos erros 500 se resolve na primeira nova tentativa. Se você receber erros 500 persistentes por mais de alguns minutos, consulte a página de status da Anthropic ou o endpoint de status do gateway para verificar incidentes conhecidos. 

Não modifique sua requisição em resposta a um 500 — o problema está no servidor. Alterar seu prompt, reduzir o contexto ou trocar de modelo não ajudará e desperdiça tempo de desenvolvimento na investigação de um problema que não é seu. As únicas ações necessárias são: tentar novamente, aguardar mais tempo se as novas tentativas falharem e emitir um alerta se o problema persistir além de um período razoável (5-10 minutos de falhas contínuas). 

## Erro 529 — "O servidor do Claude está sobrecarregado" (overloaded_error) 

O código de status 529 é específico da Anthropic e significa que a API está enfrentando alta demanda — o modelo solicitado está temporariamente no limite de capacidade. Ao contrário de um 429 (que significa que o limite de requisições YOUR foi excedido), um 529 significa que SYSTEM está sobrecarregado, independentemente dos seus limites individuais. Você não fez nada errado; simplesmente há mais demanda do que capacidade computacional disponível naquele momento. 

Os erros 529 são mais comuns nos horários de pico (horário comercial dos EUA), imediatamente após o lançamento de novos modelos (todos testam o novo modelo simultaneamente) e durante momentos de viralização, quando o uso aumenta repentinamente entre todos os clientes. Eles são menos comuns no Sonnet e no Haiku do que no Opus, porque o Opus exige mais capacidade computacional por requisição e tem restrições de capacidade mais rigorosas. 

Trate os erros 529 com intervalos de espera maiores do que os usados para erros 500. Comece aguardando 5-10 segundos e aumente o intervalo exponencialmente. Se você estiver desenvolvendo sistemas de produção, considere usar um modelo alternativo: quando o Opus retornar 529, use o Sonnet para aquela requisição. Um gateway com várias contas upstream também pode ajudar — a sobrecarga pode afetar os níveis de prioridade de algumas contas de forma diferente de outras, dando ao gateway mais opções de roteamento durante os picos de demanda. 

## "Nenhum upstream saudável" — Um erro de infraestrutura, não do Claude 

"Nenhum upstream saudável" não é uma mensagem retornada pela própria API do Claude. É a mensagem que um balanceador de carga ou proxy de entrada (normalmente o Envoy) emite quando todas as instâncias de backend atrás dele estão indisponíveis. Você a verá em claude.ai durante uma indisponibilidade, e também em qualquer proxy ou gateway cujo conjunto de conexões upstream esteja esgotado ou falhando nas verificações de integridade. 

Não há nada a corrigir no seu código. Trate o problema como transitório: consulte status.anthropic.com, aguarde e tente novamente com espera exponencial, exatamente como faria para um 529. Se persistir por mais de alguns minutos no endpoint oficial, trata-se de uma indisponibilidade; se vier de um gateway de terceiros, esse gateway perdeu toda a sua capacidade upstream. 

Esse é um dos tipos de falha que um gateway com várias contas foi projetado para absorver: quando uma conta upstream sofre limitação de requisições ou apresenta problemas de integridade, a requisição é encaminhada para outra, em vez de apresentar o erro a você. 

## Lógica de novas tentativas pronta para produção 

Uma boa lógica de novas tentativas trata todos os erros transitórios (429, 500, 529) de maneira uniforme, com espera exponencial e variação aleatória, enquanto trata erros permanentes (400, 401, 403) como não elegíveis para novas tentativas. O padrão é: enviar a requisição, verificar o código de status e, se for possível tentar novamente, aguardar com intervalos progressivos e repetir até N vezes; caso contrário, lançar o erro imediatamente. O número máximo de novas tentativas deve ser 3-5 para a maioria das aplicações. 

A variação aleatória evita novas tentativas sincronizadas. Se dez clientes atingirem um limite de requisições ao mesmo tempo e todos tentarem novamente após exatamente 2 segundos, todos falharão novamente de forma simultânea. Adicionar variação aleatória (multiplicar o intervalo por um fator aleatório entre 0.5 e 1.5) distribui as novas tentativas ao longo do tempo e melhora drasticamente as taxas de sucesso. Todo cliente da API do Claude em produção deve incluir variação aleatória. 

Para o Claude Code e fluxos de trabalho com agentes, implemente novas tentativas no nível do cliente HTTP, para que chamadas individuais de ferramentas e requisições de subagentes se beneficiem automaticamente. O SDK da Anthropic já inclui uma lógica básica de novas tentativas, mas você pode querer personalizar os tempos limite e o número máximo de novas tentativas para seu caso de uso. Se você usa o AI Prime Tech Unlimited, o gateway gerencia internamente as novas tentativas e o roteamento upstream, reduzindo os erros que chegam ao seu cliente. 

## Como um gateway reduz esses erros 

Um gateway com uma arquitetura bem projetada, como o AI Prime Tech Unlimited, reduz a frequência de erros de várias maneiras. Para limites de requisições (429), o gateway distribui as requisições entre várias contas de API upstream, de modo que seu limite efetivo seja a soma de todas as contas upstream, em vez da cota de uma única conta. Para erros de sobrecarga (529), o gateway pode tentar novamente usando outras contas upstream, que podem ter diferentes níveis de prioridade ou posições na fila. 

Para erros de servidor (500), o gateway pode tentar novamente de forma transparente antes de retornar o erro ao seu cliente — você recebe uma resposta um pouco mais lenta em vez de um erro. Para erros 400, o gateway não pode ajudar porque a própria requisição é inválida, mas bons gateways fornecem mensagens de erro mais claras, que ajudam você a depurar mais rapidamente do que as respostas de erro brutas da Anthropic. 

O resultado para os desenvolvedores é menos erros chegando à aplicação, menos lógica de novas tentativas necessária no cliente e desempenho mais estável durante os horários de pico. Isso é especialmente valioso para sessões do Claude Code, nas quais um erro no meio de uma tarefa pode interromper o fluxo, e para aplicações em produção, nas quais as taxas de erro afetam diretamente a experiência do usuário. O preço fixo do plano ilimitado significa que essas novas tentativas e esses redirecionamentos não geram custos adicionais para você. 

Copiar

```
import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://aiprimetech.io",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # Don't retry 400s

# Usage:
resp = call_with_retry([{"role": "user", "content": "Hello"}])
```

## Perguntas frequentes 

 O que significa 'erro da API do Claude: limite de requisições atingido'?

Significa que você excedeu o número permitido de requisições por minuto, tokens por minuto ou tokens por dia. A API retorna HTTP 429 com um cabeçalho Retry-After. Aguarde o tempo especificado e tente novamente. Um gateway com várias contas upstream pode reduzir esses erros ao distribuir suas requisições por um conjunto combinado maior de cotas de requisições. O que significa "limite excedido" no Claude?

É a forma como um limite de requisições 429 é descrito para o usuário final: sua conta consumiu a cota de requisições ou tokens para o período atual. Na API, a mesma condição retorna HTTP 429 com um cabeçalho Retry-After. Aguarde o tempo indicado e tente novamente com intervalos de espera progressivos; para uso intenso e contínuo, a solução é um plano ou gateway com mais capacidade. Por que o Claude diz "o servidor está sobrecarregado"?

Isso é HTTP 529, overloaded_error: o modelo solicitado está no limite de capacidade para todos, não apenas para você. Não há nada de errado na sua requisição. Tente novamente com espera exponencial e variação aleatória, ou encaminhe a chamada para outro modelo ou upstream até que a capacidade seja restabelecida. O que significa "nenhum upstream saudável" no Claude?

A mensagem vem do balanceador de carga que fica à frente do serviço, não da API: nenhuma instância de backend está disponível no momento. É um problema transitório — consulte a página de status, tente novamente com intervalos de espera progressivos e não altere seu código. Quando vem de um gateway, significa que todo o conjunto de upstreams está indisponível ou sujeito a limitações de requisições. Como corrijo o erro 400 da API do Claude?

Leia o corpo da mensagem de erro — ele informa exatamente o que está errado. Causas comuns: contexto muito longo (use /compact), ID de modelo inválido (consulte /v1/models), array de mensagens malformado ou parâmetros não compatíveis. Os erros 400 nunca são transitórios, e a requisição não deve ser repetida sem ser corrigida. O que é o erro 529 overloaded_error?

Um 529 significa que a infraestrutura da Anthropic está no limite de capacidade para o modelo solicitado. Trata-se de uma sobrecarga de todo o sistema, não do seu limite individual de requisições. Aguarde 5-10 segundos e tente novamente com espera exponencial. Considere usar um modelo menos sobrecarregado (Sonnet em vez de Opus) durante os horários de pico. O plano ilimitado elimina os erros de limite de requisições?

Ele os reduz significativamente porque o gateway distribui as solicitações entre várias contas de provedores, multiplicando os limites de requisições disponíveis. No entanto, limites de requisições de uso justo ainda se aplicam no nível do gateway. Você verá muito menos erros 429 do que em uma única conta direta da Anthropic, especialmente durante o uso intenso do Claude Code. Devo tentar novamente em caso de erro 500?

Sim. Os erros 500 são problemas transitórios no servidor. Repita exatamente a mesma solicitação após 1-2 segundos, com espera exponencial entre as tentativas. Não modifique sua solicitação — o erro não é causado pelos dados enviados. Se os erros 500 persistirem por mais de 5 minutos, consulte a página de status do provedor. Como corrigir "Erro 400 da API Claude: a entrada é longa demais para o modelo solicitado"?

Reduza os tokens enviados: corte o histórico de conversa reenviado, limite a entrada com uma contagem de tokens antes de cada solicitação ou migre para um modelo com contexto de 1M, como o Fable 5, se realmente precisar da entrada completa. Reenviar os mesmos dados não ajudará — a solicitação precisa ser menor ou a janela de contexto, maior.  

Comece a usar o Claude em minutos

Obtenha uma chave de API — sem precisar de conta na Anthropic nem de lista de espera.[Obtenha sua chave de API](/register) 

AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários.    

## Mais guias da API do Claude

[Como obter uma chave da API Claude](/pt/learn/how-to-get-a-claude-api-key/)[Preços da API Claude explicados](/pt/learn/claude-api-pricing-explained/)[A maneira mais barata de usar a API do Claude](/pt/learn/cheapest-way-to-use-claude-api/)[Cursor ilimitado com a API do Claude](/learn/use-claude-api-with-cursor/)[Acesso ilimitado ao Claude Code](/pt/learn/use-claude-api-with-claude-code/)[Gateway da API do Claude vs. acesso direto à Anthropic](/pt/learn/claude-api-vs-anthropic-direct/)[Use Claude com o SDK da OpenAI: endpoint compatível com OpenAI, streaming, ferramentas e limites](/pt/learn/openai-compatible-claude-api/)[Modelos Claude explicados: uma comparação entre Claude Opus, Sonnet, Haiku e Fable — todos os modelos da API Claude, nomes e preços dos modelos Anthropic (2026)](/pt/learn/claude-api-models-compared/)[Pagamento da API do Claude com criptomoedas](/pt/learn/claude-api-with-crypto-payment/)[Acesso à API do Claude sem lista de espera](/pt/learn/claude-api-without-waitlist/)[Como reduzir o uso de tokens do Claude](/pt/learn/how-to-reduce-claude-token-usage/)[Cline ilimitado com a API do Claude](/pt/learn/use-claude-api-with-cline/)[Roo Code ilimitado com a API do Claude](/pt/learn/use-claude-api-with-roo-code/)[Claude ilimitado nas IDEs da JetBrains](/pt/learn/use-claude-api-with-jetbrains/)[Aider com Claude por meio de um gateway: ANTHROPIC_API_BASE, arquivos de configuração, modo arquiteto e correções](/pt/learn/use-claude-api-with-aider/)[Claude ilimitado no VS Code](/pt/learn/use-claude-api-with-vscode/)[Configuração do OpenCode para Claude: configuração do opencode.json, modelos e erros comuns](/pt/learn/use-claude-api-with-opencode/)[Hermes Agent com Claude por meio de um gateway: configuração de provedor personalizado, controles de custos e correções](/pt/learn/run-hermes-agent-with-claude-api/)[Executando OpenClaw ilimitado com Claude](/pt/learn/run-openclaw-with-claude-api/)[O que significa uma API compatível com a Anthropic](/pt/learn/anthropic-compatible-api/)[Chave de API do Claude Code — ANTHROPIC_API_KEY: como obtê-la, configurá-la e quando usar claude setup-token em seu lugar](/pt/learn/claude-code-api-key-setup/)[Custos da API do Claude Code — Preços e como reduzi-los](/pt/learn/claude-code-api-costs/)[Como comprar créditos da API Claude](/pt/learn/buy-claude-api-credits/)[API Claude gratuita: existe uma chave de API Claude gratuita e o que realmente é gratuito em 2026?](/pt/learn/claude-api-free-trial/)[API do Claude vs assinatura Claude Pro/Max — Qual escolher](/pt/learn/claude-api-vs-subscription/)[Codex CLI com um provedor personalizado: config.toml, modelos GPT e Claude, extensão para IDE e correções](/pt/learn/use-claude-api-with-codex/)[Conectando Claude ao n8n](/pt/learn/use-claude-api-with-n8n/)[Roteando LiteLLM para Claude](/pt/learn/use-claude-api-with-litellm/)[Usando Claude no Kilo Code](/pt/learn/use-claude-api-with-kilo-code/)[GitHub Copilot Chat com Claude por meio de um gateway: configuração de Custom Endpoint, modo agente e correções](/pt/learn/use-claude-api-with-github-copilot/)[Conecte o Zed ao Claude por meio do gateway](/pt/learn/use-claude-api-with-zed/)[Conecte o Cherry Studio ao Claude](/pt/learn/use-claude-api-with-cherry-studio/)[ChatAnthropic no LangChain: importação, base_url, streaming, ferramentas e erros](/pt/learn/use-claude-api-with-langchain/)[SDK de Python da Anthropic: instale, defina base_url, use streaming e trate erros](/pt/learn/anthropic-python-sdk/)[Claude com o Vercel AI SDK: baseURL de createAnthropic, streaming e correções](/pt/learn/use-claude-api-with-vercel-ai-sdk/)[Execute o Factory Droid com o Claude](/pt/learn/use-claude-api-with-factory-droid/)[A API do Claude Code, explicada](/pt/learn/claude-code-api/)[Como integrar a API do Claude à sua aplicação](/pt/learn/claude-api-integration/)[Como obter uso ilimitado do Claude](/pt/learn/get-unlimited-claude-usage/)[O que significa acesso ilimitado à API do Claude](/pt/learn/unlimited-claude-api-access/)