Resolver problemasAtualizado em 29 de setembro de 20266 min de leitura

Erros da API do Claude: o que significa cada código e como resolver

Quando uma requisição falha, a API do Claude responde com um código HTTP e um JSON que diz o tipo do erro. Saber ler esses dois dados resolve a maior parte dos problemas em minutos.

Este guia lista os erros da API com o Claude Opus 5, a causa mais comum de cada um e o que fazer.

Tabela rápida

Os SDKs oficiais já repetem sozinhos, por padrão duas vezes, os erros 429, os 5xx e as falhas de conexão. Os erros 4xx (menos o 429) não adiantam repetir: a requisição precisa ser corrigida.

400: requisição inválida

A API entendeu a requisição, mas algo nela está errado. A mensagem do erro diz o quê. As causas mais comuns:

• temperature, top_p ou top_k no Claude Opus 5. Esses parâmetros não são aceitos no Claude Opus 5, e enviar qualquer um deles gera 400. É o erro mais comum em código copiado de exemplos antigos: apague o parâmetro.
• thinking com budget_tokens. O formato antigo de raciocínio ({"type": "enabled", "budget_tokens": N}) também gera 400 no Claude Opus 5. O raciocínio adaptativo já vem ligado por padrão; se quiser deixar explícito, use thinking={"type": "adaptive"}.
• Mensagens fora de ordem. A lista messages precisa começar com uma mensagem user. A última também não pode ser do assistant: o Claude Opus 5 não aceita que você comece a resposta por ele.
• Esquema recusado no output_config. Todo objeto do esquema precisa de "additionalProperties": false. Veja o guia de respostas em JSON.
• max_tokens acima do limite. O Claude Opus 5 aceita até 128 mil tokens de saída.
• JSON malformado ou um campo obrigatório faltando (model, max_tokens, messages).

401: chave inválida

A chave está errada, vazia ou foi revogada. Na open33, a resposta vem assim:

{"error": {"message": "Chave de acesso invalida.", "type": "authentication_error", "code": "invalid_api_key"}}

Confira se ANTHROPIC_API_KEY tem exatamente a chave do painel, sem espaço, quebra de linha ou aspas sobrando. Se você editou o ~/.bashrc ou o ~/.zshrc, abra um terminal novo antes de testar.

No Claude Code, se aparece a tela de login em vez do erro 401, a chave nem chegou a ser usada: veja o guia Claude Code pedindo login.

403: sem permissão

A chave é válida, mas não pode fazer aquela operação. Confira se está usando a chave certa para o projeto e fale com o suporte se o erro continuar.

404: URL ou modelo não encontrado

Duas causas respondem por quase todos os 404:

A URL base com /v1 no final. Os SDKs e o Claude Code acrescentam /v1/messages sozinhos. Com https://api.open33.tech/v1 na URL base, a chamada vai para /v1/v1/messages e a API responde:

{"error": {"message": "Endpoint nao encontrado.", "type": "invalid_request_error", "code": "not_found"}}

Use exatamente https://api.open33.tech, sem barra e sem /v1. Só no cURL, em que você escreve o endereço completo, o caminho é https://api.open33.tech/v1/messages.

O nome do modelo errado. O identificador do Claude Opus 5 é claude-opus-5, com hífens e sem espaços.

413: requisição grande demais

O corpo da requisição passou do tamanho permitido. Reduza o conteúdo: resuma o histórico antigo da conversa ou divida documentos longos em partes.

429: limite atingido

Você passou do limite de requisições ou de tokens por período. Toda conta de API tem limite, inclusive direto na Anthropic. Na open33, os limites de cada plano aparecem no painel, e a API volta a responder na janela seguinte.

O que fazer:

1. Deixe o SDK repetir. Ele já espera e tenta de novo sozinho. Quando a resposta traz o cabeçalho retry-after, ele diz quantos segundos esperar.
2. Espalhe as requisições. Rajadas de chamadas em paralelo batem no limite mais rápido do que o mesmo volume distribuído no tempo.
3. Gaste menos tokens por requisição. Envie só o contexto necessário e use cache de prompt no que se repete.
4. Mude de plano se o 429 virar rotina no seu uso normal.

500 e 529: erro no servidor ou sobrecarga

São falhas temporárias, do lado do servidor. O SDK já repete sozinho. Se você faz as chamadas sem SDK, repita com intervalos crescentes (1 s, 2 s, 4 s...) e um número máximo de tentativas.

Quando a resposta vem, mas não do jeito esperado

Nem todo problema é um código de erro. Confira o campo stop_reason da resposta:

• "max_tokens": a resposta foi cortada porque atingiu o max_tokens. Aumente o valor; para respostas longas, use streaming.
• "refusal": o modelo recusou o pedido por segurança. Verifique o stop_reason antes de ler o texto.
• Texto vazio em content[0]: o Claude Opus 5 pode devolver outros blocos antes do texto, como os de raciocínio. Filtre os blocos com type == "text" em vez de ler sempre o primeiro.

Outro erro comum: com max_tokens alto e sem streaming, o SDK de Python recusa a requisição antes de enviá-la, porque ela pode passar de 10 minutos. A solução é usar streaming.

Tratando erros no código

Python, do erro mais específico para o mais geral:

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_BASE_URL=https://api.open33.tech

try:
    resposta = client.messages.create(
        model="claude-opus-5",
        max_tokens=16000,
        messages=[{"role": "user", "content": "Olá!"}],
    )
except anthropic.BadRequestError as e:
    print(f"Requisição inválida: {e.message}")
except anthropic.AuthenticationError:
    print("Chave inválida: confira ANTHROPIC_API_KEY.")
except anthropic.NotFoundError:
    print("URL base ou modelo errado: use https://api.open33.tech e claude-opus-5.")
except anthropic.RateLimitError:
    print("Limite atingido (429): aguarde a próxima janela.")
except anthropic.APIStatusError as e:
    print(f"Erro da API ({e.status_code}): {e.message}")
except anthropic.APIConnectionError:
    print("Falha de rede: confira a conexão.")

TypeScript, com APIConnectionError antes de APIError, porque no SDK de TypeScript o primeiro é um caso particular do segundo:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

try {
  await client.messages.create({
    model: "claude-opus-5",
    max_tokens: 16000,
    messages: [{ role: "user", content: "Olá!" }],
  });
} catch (err) {
  if (err instanceof Anthropic.AuthenticationError) {
    console.error("Chave inválida: confira ANTHROPIC_API_KEY.");
  } else if (err instanceof Anthropic.NotFoundError) {
    console.error("URL base ou modelo errado.");
  } else if (err instanceof Anthropic.RateLimitError) {
    console.error("Limite atingido (429): aguarde a próxima janela.");
  } else if (err instanceof Anthropic.APIConnectionError) {
    console.error("Falha de rede: confira a conexão.");
  } else if (err instanceof Anthropic.APIError) {
    console.error(`Erro da API (${err.status}): ${err.message}`);
  } else {
    throw err;
  }
}

Para mudar o número de tentativas automáticas, passe max_retries (Python) ou maxRetries (TypeScript) ao criar o cliente.