Vai trocar para o Claude Sonnet 5.5 na API? O que revisar no seu código antes e depois

Fala aí, beleza? Se tu acha que migrar pro Sonnet 5.5 é só trocar uma string no código, se liga nisso: segundo o guia de migração da própria Anthropic, trocar só o model ID para claude-sonnet-5-5 pode quebrar a integração

Às vezes quebra com erro 400, bem na cara

E às vezes quebra em silêncio, com a requisição dando sucesso e algo se perdendo no caminho 😛

O Claude Sonnet 5.5 saiu em 28/09/2026, como segundo modelo da família Claude 5.5 (o Opus 5.5 veio na semana anterior), e já está disponível no Claude.ai, na API e em AWS, Google Cloud e Azure

Este post é um checklist do SEU código: o que revisar antes de virar a chave e o que conferir depois que o Sonnet 5.5 já estiver respondendo

Por que a troca de modelo mexe no seu código (e não só na conta)?

Do lado do custo, a conta é tranquila: o preço por token é o mesmo do Sonnet 5, US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de saída

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O cache read sai a US$ 0,20/M, o cache write a US$ 2,50/M e o cache write de 1h a US$ 4,00/M, sem sobretaxa de contexto longo

O contexto é de 1M tokens e a saída máxima é de 128K tokens por resposta (até 300K via Batch API, que está em beta)

A Anthropic fala em saída mais de 30% mais rápida que o Sonnet 5 e custo por tarefa até 30% menor, porque o modelo usa menos tokens e menos chamadas de ferramenta

Porém, tem um detalhe: esse ganho só aparece se a sua integração não quebrar no meio do caminho haha

E o prazo também importa:

• O Sonnet 5 continua disponível, com aposentadoria prevista para não antes de 30/06/2027
• O Sonnet 5.5 tem aposentadoria prevista para não antes de 28/09/2027
• O Sonnet 4.5 (claude-sonnet-4-5-20250929) foi marcado como descontinuado em 30/09/2026 e se aposenta na Claude API em 30/11/2026, e a Anthropic recomenda migrar para o Sonnet 5.5

Ou seja: quem está no Sonnet 5 tem folga, quem está no 4.5 tem relógio correndo

Antes de começar: o que ter em mãos

Três coisas, beleza?

1. De qual modelo você está saindo

O guia oficial Migrating to Claude Sonnet 5.5 tem checklist separado para cada origem: Sonnet 5, Sonnet 4.6, Sonnet 4.5, Sonnet 4, Claude 3.7 Sonnet e Haiku 4.5

O que muda pra você depende de onde você parte, então abre o checklist certo

2. Em qual plataforma a sua aplicação roda

Porque o identificador muda conforme o lugar

Se liga num detalhe de nome: o anúncio de lançamento fala em AWS e Azure, e a documentação de identificadores fala em Amazon Bedrock (o serviço da AWS) e Microsoft Foundry (o serviço da Microsoft)

Na tabela uso os nomes da documentação de identificadores:

Repara que não tem sufixo de data no ID, diferente de modelos mais antigos como o claude-sonnet-4-5-20250929

3. Uma suíte de testes de integração que chame a API de verdade

Mock não pega erro 400 de configuração que o modelo novo passou a rejeitar

Se você vai pedir pra IA fazer essa migração por você, vale revisar a spec antes de deixar ela sair mexendo, porque migração de modelo tem MUITO detalhe pequeno que passa batido

Checklist ANTES da troca: o que revisar no código

Aqui é onde mora a maior parte do trabalho

Os trechos abaixo são ilustrativos (Python, usando o SDK da Anthropic), a ideia é tu reconhecer o padrão no seu próprio código

Passo 1: o identificador do modelo é configurável?

Primeira pergunta: onde está escrito o nome do modelo no seu código?

Se a resposta é "espalhado em 14 arquivos", já sabe o primeiro trabalho kkk

O ideal é o ID vir de config ou variável de ambiente da SUA aplicação, num lugar só:

import os

# Antes: fixo no código
# MODEL = "claude-sonnet-5"

# Depois: vem da config da sua aplicação
MODEL = os.environ.get("APP_CLAUDE_MODEL", "claude-sonnet-5")

resp = client.messages.create(
    model=MODEL,
    max_tokens=1024,
    messages=[{"role": "user", "content": "Olá"}],
)

Assim a troca vira uma mudança de config, e voltar atrás também

O erro comum deste passo: catálogo de modelos fixo no código

Isso não é teoria, aconteceu de verdade depois do lançamento

Vários projetos open source com lista de modelos hardcoded rejeitaram claude-sonnet-5-5

O flywheel, por exemplo, respondia "not a claude model flywheel knows; did you mean claude-sonnet-5" (issue #768, corrigida no PR #771)

O opensre (#6497) e o terminalx (#256) tiveram o mesmo tipo de problema

Se você precisa validar o modelo, uma saída é conferir contra o endpoint GET /v1/models, que lista os modelos disponíveis e devolve id, display_name, created_at, max_input_tokens, max_tokens e um objeto capabilities

# ids_disponiveis: lista de "id" vinda de GET /v1/models
# (atenção à paginação: after_id / before_id, limit padrão 20, de 1 a 1000)

def validar_modelo(model, ids_disponiveis):
    if model not in ids_disponiveis:
        raise ValueError(f"Modelo {model} não está disponível nesta conta")
    return model

Tome cuidado com a paginação: com o limit padrão de 20, se você ler só a primeira página pode achar que o modelo não existe 🙂

Passo 2: o parsing da resposta lê os blocos pelo tipo?

Esse aqui pega MUITA gente

No Sonnet 5.5 a resposta pode começar com blocos de thinking

Então aquele código clássico que pega content[0].text simplesmente quebra

# Antes: assume que o primeiro bloco é texto
# texto = resp.content[0].text

# Depois: seleciona pelo tipo, não pela posição
textos = [b.text for b in resp.content if b.type == "text"]
thinking = [b for b in resp.content if b.type == "thinking"]
ferramentas = [b for b in resp.content if b.type == "tool_use"]

texto = "\n".join(textos)

O erro comum deste passo: corrigir só o lugar que deu erro e esquecer os outros

Faz uma busca no projeto por content[0] e trata todos de uma vez

Passo 3: tem thinking desligado na requisição?

Se o seu código manda thinking: {"type": "disabled"}, o Sonnet 5.5 devolve erro 400

# Isto gera erro 400 no Sonnet 5.5:
# thinking={"type": "disabled"}

Pra rodar sem thinking antecipado, o caminho é usar a configuração mais baixa, a between_tools

Só que ela só é aceita com effort low, medium ou high

O formato exato dessa configuração tá no guia de migração, confere lá antes de mexer pra não trocar um 400 por outro

O erro comum deste passo: remover o disabled e combinar between_tools com um effort fora dessa lista

Passo 4: o seu código força o uso de ferramenta?

tool_choice igual a any ou tool agora dá erro 400

# Antes (erro 400 no Sonnet 5.5):
# tool_choice={"type": "any"}

# Depois:
tool_choice = {"type": "auto"}

E se você precisava garantir a saída estruturada?

A recomendação é usar auto junto com strict tool use ou structured outputs

O erro comum deste passo: no Amazon Bedrock só vale auto, então não adianta procurar outro caminho por lá

Passo 5: usa computer use?

Na Claude API e no Google Cloud, é obrigatório trocar a ferramenta computer_20251124 pela computer_toolset_20260801

# Antes:
# "type": "computer_20251124"

# Depois (Claude API e Google Cloud):
# "type": "computer_toolset_20260801"

O erro comum deste passo: trocar o modelo e esquecer da definição da ferramenta, que costuma morar num arquivo separado de config de tools

Passo 6: usa a advisor tool?

Se a sua arquitetura usa um modelo como advisor do Sonnet, atenção: Opus 4.8, Opus 4.7 e Sonnet 5 não podem ser usados como advisors do Sonnet 5.5

Aqui não tem trecho de código pra mostrar, é decisão de arquitetura: revise qual modelo você aponta como advisor antes da troca

As falhas silenciosas: quando a requisição dá certo mas algo se perdeu

Erro 400 é chato, mas pelo menos avisa

O perigo de verdade é a requisição voltar com sucesso e o contexto ter ido embora sem ninguém perceber…

Caso 1: loop de tool use que altera os blocos de thinking

Sintoma: o loop de ferramentas roda, mas o raciocínio entre as chamadas parece perder o fio

Causa: o seu código filtra, edita ou descarta os blocos de thinking antes de mandar o próximo turno

Solução: devolva os blocos de thinking sem alteração (inclusive os vazios) junto com o resto do turno do assistente

# Devolve o turno do assistente inteiro, sem filtrar thinking
messages.append({"role": "assistant", "content": resp.content})

Como prevenir: saiba que as notas de progresso entre chamadas de ferramenta chegam como blocos de thinking com texto de resumo, então não trate thinking como "lixo pra jogar fora"

Caso 2: conversa editada no meio do caminho

Sintoma: erro 400 ao continuar uma conversa que funcionava

Causa: a API verifica se algo antes de um bloco de thinking do Sonnet 5.5 mudou (system prompt, ferramentas ou uma mensagem anterior)

Para contas criadas a partir de 31/08/2026, reenviar o bloco depois de uma mudança dessas retorna erro 400

Solução: mantenha a conversa append-only, ou seja, só adiciona no fim, nunca edita o que já foi

Como prevenir: em vez de editar o system prompt no meio da sessão, mande uma mensagem de sistema no meio da conversa, recurso que o Sonnet 5.5 suporta

Caso 3: histórico reaproveitado por outra conta

Sintoma: a requisição dá sucesso, mas o modelo se comporta como se não tivesse o raciocínio anterior

Causa: os blocos de thinking do Sonnet 5.5 só valem na conta que os gerou ou em conta vinculada a ela

Se outra conta reenviar esses blocos, a API descarta tudo antes de chegar ao modelo e a requisição dá sucesso mesmo assim

Solução: não compartilhe histórico com thinking entre contas que não são vinculadas

Como prevenir: se você tem ambientes em contas diferentes (staging numa, produção noutra), não reaproveite conversas salvas de um no outro

Checklist DEPOIS da troca: logs e testes de integração

Virou a config? Massa, agora é provar que o modelo novo é mesmo quem tá respondendo e que nada quebrou

Passo 1: logue o campo model de cada resposta

A resposta da Messages API traz um campo model com o identificador do modelo que respondeu

Esse campo é a sua prova, não a config que você ACHA que subiu

import logging

logger = logging.getLogger("claude")

resp = client.messages.create(model=MODEL, max_tokens=1024, messages=messages)
logger.info("modelo_pedido=%s modelo_respondeu=%s", MODEL, resp.model)

O erro comum deste passo: logar só o modelo que você pediu, sem registrar o que veio na resposta

Passo 2: testes de integração que conferem modelo e formato

O teste precisa olhar duas coisas: qual modelo respondeu e se o formato dos blocos é o que o seu código espera

def test_resposta_sonnet_5_5():
    resp = client.messages.create(
        model=MODEL,
        max_tokens=256,
        messages=[{"role": "user", "content": "Responda apenas: ok"}],
    )
    assert resp.model == MODEL

    tipos = {b.type for b in resp.content}
    assert "text" in tipos
    assert tipos <= {"text", "thinking", "tool_use"}

O erro comum deste passo: assumir que o teste vale igual em qualquer plataforma

O comportamento exato do campo model quando a chamada passa por Bedrock, Google Cloud ou Foundry não está documentado na fonte que usei, então confirme na sua plataforma antes de travar esse assert

Passo 3: compare com o modelo anterior e mantenha a volta fácil

Rode os mesmos cenários com o modelo antigo e com o Sonnet 5.5 e compare as saídas que importam pro seu produto

Como o Sonnet 5 segue disponível, deixa a troca reversível pela config do Passo 1 do checklist anterior: se algo esquisito aparecer em produção, voltar é só mudar a variável

E se os ajustes de código foram feitos com ajuda de IA, aplica o mesmo cuidado de revisar o código gerado antes do PR, migração não é lugar pra modo 100% vibe coder haha

O erro comum deste passo: apagar o código e a config do modelo antigo no mesmo deploy da troca

Próximo passo: migrar com rede de proteção

Recapitulando os três pilares:

• ID configurável: o modelo vem de config, nunca de um catálogo fixo no código
• Parsing pelo tipo: text, thinking e tool_use selecionados pelo tipo, nunca por content[0]
• Log do model: cada resposta registra qual modelo respondeu de verdade

Por cima disso, revisa os pontos que dão 400 (thinking disabled, tool_choice any/tool, computer use, advisor) e os que falham em silêncio (thinking alterado, conversa editada, histórico de outra conta)

O próximo passo prático: abre o guia oficial "Migrating to Claude Sonnet 5.5" no checklist do SEU modelo de origem e roda a suíte de integração antes de virar a config em produção

E se você ainda está no Sonnet 4.5, lembra que a aposentadoria na Claude API é em 30/11/2026, então melhor não deixar pra última semana 😀

Até o próximo post!