//
Busque em todas as páginas da documentação
Esta página infere um layout genérico de lista de referência: ela agrupa as configurações de retentativa e timeout do SDK Python do anthropic por onde são configuradas, para que você possa encontrar a opção correta sem reler toda a referência do SDK.
Todas as configurações mostradas se aplicam igualmente a Anthropic() e AsyncAnthropic(), a menos que observado o contrário.
Defina estas opções ao construir o cliente. Elas se aplicam a todas as solicitações feitas através dessa instância do cliente, a menos que substituídas por solicitação.
import anthropic
client = anthropic.Anthropic(
max_retries=4, # padrão é 2
timeout=30.0, # segundos; padrão é 600.0 (10 minutos)
)| Configuração | Tipo | Padrão | O que controla |
|---|---|---|---|
max_retries | int | 2 | Quantas vezes o SDK retenta automaticamente uma solicitação após uma falha retentável, antes de levantar uma exceção. |
timeout | float ou httpx.Timeout | 600.0 segundos | O limite de tempo de relógio para uma única tentativa de solicitação. Aplica-se por tentativa, não à sequência inteira de retentativas. |
base_url | str | https://api.anthropic.com | Não é uma configuração de retentativa/timeout, mas comumente definida junto com elas ao rotear através de um proxy - incluída aqui, pois é definida no mesmo local de chamada. |
Use with_options(...) para substituir uma configuração para uma única chamada sem alterar os padrões do cliente.
# Uma chamada precisa de um timeout mais apertado e sem retentativas - uma solicitação de UI sensível à latência
response = client.with_options(
max_retries=0,
timeout=5.0,
).messages.create(
model="claude-sonnet-5",
max_tokens=200,
messages=[{"role": "user",
| Forma da chamada | Efeito |
|---|---|
client.with_options(max_retries=N) | Substitui a contagem de retentativas para chamadas feitas no objeto retornado; o client original não é alterado. |
client.with_options(timeout=N) | Substitui o timeout por tentativa da mesma forma. |
client.with_options(max_retries=N, timeout=N) | Ambas as substituições podem ser combinadas em uma única chamada. |
with_options(...) retorna um novo objeto semelhante a um cliente; ele não modifica o client original, portanto, o padrão é seguro para usar inline por chamada sem afetar outros caminhos de código que compartilham o mesmo cliente.
| Falha | Retentado por padrão? | Por quê |
|---|---|---|
Erro de rede/conexão (APIConnectionError) | Sim | Transitório - a solicitação pode não ter chegado ao servidor. |
408 Request Timeout | Sim | Transitório - o servidor desistiu de esperar; seguro tentar novamente. |
409 Conflict | Sim | Frequentemente transitório no uso da API (por exemplo, um recurso em um estado temporário). |
429 Too Many Requests (RateLimitError) | Sim | Transitório - espere e retente, respeitando retry-after quando presente. |
Erros de servidor 5xx | Sim | Transitório - um problema na infraestrutura da Anthropic, não na sua solicitação. |
400 Bad Request | Não | Não retentável - a solicitação em si está malformada; retentar reproduz o mesmo erro. |
401 Unauthorized | Não | Não retentável - uma chave de API inválida ou ausente não se corrigirá em uma retentativa. |
404 Not Found | Não | Não retentável - tipicamente um ID de modelo ou endpoint inválido. |
retry-after de uma resposta 429, quando presente, é respeitado como um tempo mínimo de espera antes da próxima tentativa.max_retries é a principal alavanca que você controla.| Preocupação | Comportamento |
|---|---|
O que timeout limita | Cada tentativa individual de HTTP, não o tempo total em todas as retentativas. |
| Tempo de relógio de pior caso | Pode atingir aproximadamente timeout × (max_retries + 1) se cada tentativa expirar e for retentada. |
| Solicitações de streaming | timeout ainda se aplica ao estabelecer a conexão e receber os primeiros bytes; um stream lento, mas em progresso, não é interrompido pelo mesmo relógio. |
| Passando um número simples | Tratado como segundos para Anthropic() e AsyncAnthropic() - o SDK Python não usa milissegundos. |
| Cenário | max_retries sugerido | timeout sugerido | Raciocínio |
|---|---|---|---|
| Solicitação interativa, voltada para o usuário | 1-2 | 10-30 segundos | Usuários notam atraso; falhe rapidamente e apresente um erro em vez de retentar por muito tempo. |
| Tarefa em lote ou trabalho ETL em segundo plano | 4-6 | 60+ segundos | Ninguém está esperando de forma síncrona; prefira o sucesso eventual à velocidade. |
Loop de agente longo com max_tokens grande | Padrão do cliente (2), combinado com streaming | 600 segundos (padrão do cliente) geralmente é suficiente, pois o streaming evita o risco de timeout de uma única chamada não-streaming gigante | Streaming (veja Relacionados) é a principal correção para timeouts de saída grande, não apenas um valor timeout maior. |
| Chamada de verificação de integridade ou smoke-test | 0 | 5-10 segundos | Você quer saber imediatamente se algo está errado, não após várias tentativas. |
2.
O SDK retenta uma falha transitória até duas vezes adicionais (três tentativas no total) antes de levantar uma exceção.
600.0 segundos (10 minutos), aplicado por tentativa.
Não.
client.with_options(...) retorna um novo objeto com as substituições aplicadas; o client original e seus padrões não são alterados.
Apenas a uma tentativa.
Se cada tentativa expirar e for retentada, o tempo de relógio de pior caso pode atingir aproximadamente timeout × (max_retries + 1).
Não.
400, 401, 403 e 404 são tratados como não retentáveis, pois a solicitação em si (não a rede ou o servidor) é o problema, e retentá-la inalterada falharia novamente.
Não.
Ambas as classes de cliente aceitam os mesmos argumentos de construtor max_retries e timeout e suportam o mesmo padrão with_options(...).
Sim.
Quando a resposta inclui um cabeçalho retry-after, o SDK o respeita como um atraso mínimo antes da próxima tentativa de retentativa.
Essa é uma escolha razoável.
Uma verificação de integridade geralmente quer saber imediatamente se a API está acessível, em vez de mascarar uma interrupção real por várias tentativas de retentativa.
Sim, usando o mesmo padrão with_options(timeout=...) por chamada, ou definindo timeouts diferentes em instâncias de cliente separadas se a divisão for consistente em sua aplicação.
Não diretamente.
max_retries aborda falhas, não lentidão; uma solicitação que tem sucesso, mas é simplesmente lenta, é uma preocupação de timeout, e para saídas grandes, mudar para streaming é geralmente a melhor correção.
A exceção tipada que corresponde à falha subjacente - por exemplo, anthropic.RateLimitError para retentativas de 429 esgotadas, ou anthropic.APIConnectionError para retentativas de erro de rede esgotadas. Veja a página de referência de exceções para o mapeamento completo.
max_retries e timeoutmax_tokens grandesVersões da Pilha: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial
anthropicpara Python (último lançamento 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.