Boas Práticas Fundamentais da API Claude

Vinte e cinco práticas para autenticação, requisições e tratamento de erros confiáveis ao construir sobre a API Claude com o SDK oficial do Python.

Organizado desde a configuração e autenticação até o design de requisições, tratamento de erros e seleção de modelos.

Como Usar Esta Lista

• Trate a seção A como higiene de configuração não negociável antes de escrever qualquer código de aplicação.
• Revisite a seção C sempre que um novo modo de falha aparecer nos logs de produção.
• Use a seção D quando estiver escolhendo um modelo pela primeira vez, e novamente sempre que o custo ou a latência se tornarem uma preocupação.

A - Autenticação e Configuração

• Nunca codifique sua chave de API diretamente no código fonte. Use a variável de ambiente ANTHROPIC_API_KEY ou um gerenciador de segredos, e adicione .env ao .gitignore antes do seu primeiro commit.
• Falhe rapidamente quando a chave de API estiver faltando. Verifique a chave explicitamente na inicialização e gere um erro claro, em vez de deixar um 401 críptico aparecer profundamente em sua pilha de chamadas mais tarde.
• Use chaves de API separadas por ambiente. Chaves de desenvolvimento, staging e produção permitem que você revogue ou rotacione uma sem afetar as outras.
• Fixe a versão do SDK anthropic em seu arquivo de dependências. Uma dependência não fixada pode trazer mudanças que quebram a compatibilidade em uma instalação nova; atualize deliberadamente em vez disso.
• Construa o cliente uma vez e reutilize-o. Crie anthropic.Anthropic() na inicialização da aplicação ou no carregamento do módulo, não por requisição ou por chamada de função.

B - Design de Requisições

• Sempre defina max_tokens deliberadamente, não para um padrão arbitrário. Muito baixo trunca a saída útil; muito alto desperdiça orçamento em tarefas que não precisam disso.
• Use prompts do sistema para instruções persistentes, não para a primeira mensagem do usuário. Manter as instruções de função/restrição em system mantém o histórico de messages focado na conversa real.
• Reduza a temperatura para tarefas factuais, estruturadas ou determinísticas. Reserve valores mais altos para geração genuinamente criativa ou exploratória.
• Reenvie o histórico completo da conversa em cada chamada. A API é sem estado; não há sessão no lado do servidor para referenciar, então o cliente é o proprietário do estado da conversa.
• Prefira temperatura em vez de top_p para a maioria dos ajustes. Ajuste um controle deliberadamente em vez de alterar temperature e top_p ao mesmo tempo, o que torna o comportamento mais difícil de prever.
• Mantenha prompts e instruções do sistema no controle de versão. Trate o texto do prompt como código, revise as mudanças nele da mesma forma que revisaria mudanças na lógica.

C - Tratamento de Erros e Resiliência

• Defina um max_retries sensato no cliente. O backoff exponencial integrado do SDK lida com 429/5xx automaticamente; não o desative sem um motivo específico.
• Capture tipos de exceção específicos, não um Exception genérico. anthropic.AuthenticationError, anthropic.RateLimitError e anthropic.BadRequestError apontam para uma correção diferente.
• Nunca retente erros 4xx, exceto 429. Uma requisição malformada falha identicamente em cada tentativa; corrija a requisição em vez de retentá-la.
• Adicione jitter à qualquer lógica de retentativa personalizada. Sem variância aleatória, muitos clientes que estão em backoff com o mesmo cronograma podem ressincronizar e reativar o mesmo limite de taxa.
• Defina um timeout de requisição apropriado ao seu caso de uso. Gerações de streaming longas precisam de um timeout mais longo do que completações curtas e simples.
• Registre códigos de status e mensagens de erro, mas redija os cabeçalhos da requisição. Dump's completos de requisição podem vazar sua chave de API nos logs se não forem limpos primeiro.
• Monitore usage.input_tokens e usage.output_tokens no tráfego real. Contagens de tokens impulsionam tanto o custo quanto o uso da janela de contexto; não opere às cegas em nenhum deles.

D - Seleção de Modelo e Custo

• Use Claude Sonnet 5 como padrão, a menos que você tenha um motivo específico para alterá-lo. É o padrão balanceado atual em toda a linha.
• Roteie tarefas simples e de alto volume para Claude Haiku 4.5. Classificação, marcação e extração curta raramente precisam de um modelo principal.
• Reserve Claude Opus 4.8 ou Claude Fable 5 para tarefas genuinamente difíceis e de várias etapas. Usar um modelo principal em todos os lugares infla o custo sem um benefício de qualidade correspondente para trabalho simples.
• Centralize strings de ID de modelo como constantes nomeadas. Uma futura troca de modelo deve ser uma mudança de uma linha, não uma busca e substituição em toda a base de código.
• Verifique os IDs de modelo e preços atuais antes de codificá-los. Nomes de modelos, limites de contexto e preços mudam à medida que novas versões são lançadas; não confie em documentação desatualizada ou dados de treinamento.
• Orce para preços pós-introdução, não apenas taxas de lançamento. Alguns modelos são lançados com um preço introdutório por tempo limitado que aumenta em uma data anunciada; planeje em torno da taxa estável.

E - Arquitetura e Manutenibilidade

• Envolva o cliente SDK assim que sua base de código tiver múltiplos pontos de chamada. Um wrapper fino centraliza o modelo padrão, retentativas, timeout e tratamento de erros em vez de repeti-los em todos os lugares.
• Mantenha o uso do cliente síncrono e assíncrono separados. Use anthropic.AsyncAnthropic dentro do código asyncio e anthropic.Anthropic em código síncrono; não os misture em um único caminho de chamada.

FAQs

Relacionado

• Entendendo o Ciclo de Vida da Requisição da API Claude - o fluxo de requisição que estas práticas protegem.
• Tratando Limites de Taxa com Exponential Backoff - as práticas de retentativa na seção C, em profundidade.
• Códigos de Erro da API Claude e Referência de Solução de Problemas - o catálogo completo de erros por trás da seção C.
• Selecionando um Modelo: Claude Fable 5, Opus 4.8, Sonnet 5 e Haiku 4.5 - a comparação por trás da seção D.
• Construindo um Wrapper Reutilizável para o Cliente da API Claude - o padrão por trás da seção E.

Versões da Pilha: Escrito contra a linha de modelos Claude atual em ~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 do Python anthropic (última versão 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.