Erros

​

Erros HTTP

Nossa API segue um formato previsível de código de erro HTTP:

• 400 - invalid_request_error: Houve um problema com o formato ou conteúdo da sua solicitação. Também podemos usar esse tipo de erro para outros códigos de status 4XX não listados abaixo.

• 401 - authentication_error: Há um problema com sua chave de API.

• 403 - permission_error: Sua chave de API não tem permissão para usar o recurso especificado.

• 404 - not_found_error: O recurso solicitado não foi encontrado.

• 413 - request_too_large: A solicitação excede o número máximo permitido de bytes.

• 429 - rate_limit_error: Sua conta atingiu um limite de taxa.

• 500 - api_error: Ocorreu um erro inesperado interno nos sistemas da Anthropic.

• 529 - overloaded_error: A API da Anthropic está temporariamente sobrecarregada.

  Erros 529 podem ocorrer quando as APIs da Anthropic experimentam alto tráfego entre todos os usuários. Em casos raros, se sua organização tiver um aumento acentuado no uso, você pode ver esse tipo de erro. Para evitar erros 529, aumente seu tráfego gradualmente e mantenha padrões de uso consistentes.

Ao receber uma resposta streaming via SSE, é possível que um erro ocorra após retornar uma resposta 200, caso em que o tratamento de erros não seguiria esses mecanismos padrão.

​

Formatos de erro

Os erros são sempre retornados como JSON, com um objeto error de nível superior que sempre inclui valores type e message. Por exemplo:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  }
}

De acordo com nossa política de versionamento, podemos expandir os valores dentro desses objetos, e é possível que os valores de type aumentem ao longo do tempo.

​

ID da solicitação

Cada resposta da API inclui um cabeçalho único request-id. Este cabeçalho contém um valor como req_018EeWyXxfu5pfWkrYcMdjWG. Ao entrar em contato com o suporte sobre uma solicitação específica, inclua este ID para nos ajudar a resolver seu problema rapidamente.

Nossos SDKs oficiais fornecem esse valor como uma propriedade em objetos de resposta de nível superior, contendo o valor do cabeçalho request-id:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)
print(f"Request ID: {message._request_id}")

​

Solicitações longas

Não recomendamos definir valores grandes de max_tokens sem usar nossa API de Mensagens com streaming ou API de Lotes de Mensagens:

• Algumas redes podem descartar conexões ociosas após um período variável de tempo, o que pode fazer com que a solicitação falhe ou expire sem receber uma resposta da Anthropic.
• As redes diferem em confiabilidade; nossa API de Lotes de Mensagens pode ajudar você a gerenciar o risco de problemas de rede, permitindo que você consulte os resultados em vez de exigir uma conexão de rede ininterrupta.

Se você estiver construindo uma integração direta com a API, deve estar ciente de que configurar um TCP socket keep-alive pode reduzir o impacto de timeouts de conexão ociosa em algumas redes.

Nossos SDKs validarão que suas solicitações de API de Mensagens sem streaming não devem exceder um timeout de 10 minutos e também definirão uma opção de socket para TCP keep-alive.