Claude Opus 5.5 API: primeira solicitação e erros 400

Mesmo com uma API Key válida, sua primeira chamada ao Claude Opus 5.5 pode retornar 400 Bad Request. Confira o Model ID exato, os campos obrigatórios de Messages como max_tokens, as configurações de thinking e tool_choice. A ausência de max_tokens é um erro geral de validação de Messages, não uma nova restrição do Opus 5.5; as mudanças específicas da migração incluem thinking e escolha forçada de ferramenta.

Este guia começa com uma solicitação mínima e depois verifica os erros 400 em ordem. Use a referência da Messages API para os campos obrigatórios e o guia de migração da Anthropic para as mudanças específicas do Opus 5.5. Execute a solicitação mínima uma vez para verificar a conexão e a rota do modelo; se falhar, use o corpo do erro retornado. Antes de encaminhar claude-opus-5-5 pela BetterToken, confirme no dia da publicação ou implantação que o Model ID exato está no catálogo atual.

1. Confirme primeiro a API Key, a Base URL e o Model ID

Para a primeira solicitação, você precisa de apenas três valores: sua própria API Key da BetterToken, a Base URL Anthropic-compatible e um Model ID disponível naquele momento.

1. Entre no BetterToken Workspace e crie uma API Key na sua própria conta. Guarde-a em um gerenciador de segredos ou arquivo de ambiente local; não a envie ao Git nem a cole em mensagens de suporte.
2. Abra o catálogo atual de modelos e preços e confirme se o ID exato claude-opus-5-5 está disponível. A Anthropic o define como um ID fixo sem sufixo de data, mas disponibilidade e preço na BetterToken são dinâmicos.
3. Passe a chave por uma variável de ambiente em vez de gravá-la diretamente no código.

Você precisa de uma conta própria da BetterToken para criar uma API Key. Criar uma conta BetterToken

Para seguir os passos da interface, consulte o BetterToken Quickstart.

2. Deixe /v1 fora da Base URL, mas use-o na rota HTTP direta

Use https://bettertoken.ai como Base URL do SDK da Anthropic e https://www.bettertoken.ai/v1/messages em uma solicitação Messages HTTP direta.

https://bettertoken.ai

Não use /messages como Base URL nem acrescente /v1/messages duas vezes quando o SDK já monta a rota do recurso. Defina os três valores no shell atual:

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_MODEL_ID="claude-opus-5-5"

Execute primeiro apenas a primeira linha. O terminal aguardará uma entrada oculta: digite ou cole a API Key e pressione Enter; nenhum caractere será exibido. A chave é exportada somente no shell atual, e o histórico registra o comando read, não o segredo. Não acrescente a chave à linha de comando.

claude-opus-5-5 é o Model ID documentado pela Anthropic para a Claude Platform. Se o catálogo atual da BetterToken não exibir exatamente esse ID, pare e confirme a disponibilidade em vez de tentar adivinhar um alias.

3. Envie primeiro uma solicitação mínima

Não inclua tools, tool_choice ou thinking no primeiro teste, para que opções avançadas não escondam um problema básico de conexão.

curl --fail-with-body "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{
    \"model\": \"$CLAUDE_MODEL_ID\",
    \"max_tokens\": 4096,
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Responda apenas: pong\"}
    ]
  }"

A solicitação usa o Model ID exato, inclui um max_tokens positivo, omite thinking e não força uma chamada de ferramenta. O exemplo define max_tokens como 4096, o mesmo valor usado no exemplo de migração da Anthropic, para deixar mais espaço ao adaptive thinking e à resposta curta. Trate-o como ponto inicial de diagnóstico, não como garantia testada ou recomendação de produção; em produção, ajuste-o à resposta esperada, ao effort, ao custo e à latência.

--fail-with-body mantém o corpo da resposta em HTTP 4xx ou 5xx. Remova a API Key, prompts completos, saída do modelo e outros dados sensíveis antes de compartilhar logs.

4. Não presuma que content[0] contém texto

HTTP 200 com type de nível superior igual a message indica que o endpoint aceitou e processou a solicitação. Neste teste de resposta curta, um bloco de texto confirma que a geração terminou; adaptive thinking e o texto compartilham max_tokens, então uma resposta válida pode esgotar o limite antes de mostrar texto.

Confira estes sinais:

• o type de nível superior é message e o campo model corresponde ao modelo solicitado;
• quando o teste curto termina normalmente, stop_reason é end_turn e o array content contém pelo menos um bloco cujo type é text;
• se stop_reason for max_tokens, a resposta é válida, mas foi truncada: aumente max_tokens e repita a solicitação; se você definiu effort alto e não precisa de raciocínio profundo, também pode reduzi-lo;
• se não houver bloco de texto e stop_reason não for max_tokens, preserve a resposta completa e diagnostique essa razão de parada antes de trocar a Key ou a Base URL; a ausência de texto, sozinha, não prova falha de conexão;
• seu parser seleciona blocos por type, em vez de sempre ler content[0].text;
• usage contém contagens de Token de entrada e saída;
• o BetterToken Dashboard mostra a solicitação no horário esperado, com modelo, status, input/output/cache Token e cobrança.

A referência oficial da Anthropic Messages API documenta a estrutura, e o guia de stop_reason explica como tratar respostas truncadas. O Dashboard é útil para conciliar solicitação e uso, mas não deve ser apresentado como armazenamento garantido do prompt ou da resposta completos.

5. Verifique erros gerais de Messages e mudanças do Opus 5.5

A solicitação ainda usa um nome de modelo antigo

Troque um ID antigo ou um alias com data inventado por claude-opus-5-5. A Anthropic o define como ID fixo sem sufixo de data. Plataformas de nuvem podem usar identificadores próprios; este exemplo Anthropic-compatible da BetterToken deve usar o ID exato mostrado no catálogo atual da BetterToken.

max_tokens está ausente

Inclua um max_tokens positivo em toda solicitação Messages. Um campo ausente é um erro geral de validação da Messages API, não uma mudança da migração para o Opus 5.5. Ele limita toda a saída, incluindo thinking e texto final. Até um smoke test precisa deixar espaço para ambos; se stop_reason for max_tokens, aumente o limite e repita a solicitação, em vez de tratar a chamada como falha de conexão.

O payload desativa thinking ou define um orçamento manual

A correção mais simples é remover completamente o campo thinking. O Opus 5.5 sempre usa adaptive thinking. O guia de migração da Anthropic identifica estas duas formas antigas como rejeitadas com 400:

{"thinking": {"type": "disabled"}}

{"thinking": {"type": "enabled", "budget_tokens": 10000}}

Quando precisar declarar o campo, use {"thinking": {"type": "adaptive"}}. Controle a profundidade com output_config.effort; os níveis aceitos são low, medium, high, xhigh e max, com medium como padrão. A solicitação mínima não precisa desses campos.

O payload força tool_choice

Use apenas {"type": "auto"} ou {"type": "none"} em tool_choice. O Opus 5.5 rejeita {"type": "any"} e {"type": "tool", "name": "..."}. Em um fluxo com ferramentas, deixe o modelo escolher em auto, explique no prompt quando usar a ferramenta e valide cada schema antes de habilitar strict tool use.

6. Para outros status, leia o corpo antes de alterar a configuração

Status	Verifique primeiro	Evite
400	JSON válido; model, max_tokens, messages, thinking e tool_choice	Trocar a chave sem diagnóstico ou repetir o mesmo payload inválido
401 / 403	Chave completa, conta ou grupo correto e Base URL correta	Enviar a chave completa ao suporte
404	Uma chamada HTTP direta deve usar /v1/messages	Tratar /messages como rota completa
429	Orientação de espera, saldo, limites e histórico	Repetir em loop sem intervalo

Limpe variáveis antigas de outro provedor antes de configurar novamente o shell:

unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID

Depois de uma correção, repita a mesma solicitação mínima. Alterar modelo, endpoint, prompt e parâmetros avançados ao mesmo tempo dificulta descobrir o que realmente resolveu o problema.

7. Separe o preço de lista da Anthropic do preço atual da BetterToken

A página de lançamento da Anthropic de 22 de setembro de 2026 indicava, na Claude Platform, $4 por milhão de Input Token, $20 por milhão de Output Token, $0.20 para cache reads e $5 para cache writes. Esses são os preços de plataforma publicados oficialmente pela Anthropic no lançamento. O preço da BetterToken é dinâmico; consulte a página atual e confira uma solicitação pequena no seu próprio registro do Dashboard.

Thinking Token são cobrados como Output Token, e max_tokens cobre thinking mais o texto final. Uma carga migrada de uma configuração que desativava thinking pode, portanto, ter outro perfil de saída mesmo com o mesmo prompt. Antes da produção, consulte a página atual de preços da BetterToken e confira uma solicitação pequena no registro do Dashboard.

Antes de avançar para SDK, streaming ou tráfego de produção, reconfirme o Model ID, mantenha a chave fora do código, dimensione max_tokens, processe o conteúdo por tipo de bloco, evite forced tool choice e preserve um corpo de erro anonimizado. Continue com a BetterToken API Reference e o guia oficial de migração do Opus 5.5.