--- title: Erros da Claude API url: https://platform.claude.com/docs/pt-BR/api/errors description: Entenda os códigos de status HTTP, o formato das respostas de erro e os IDs de solicitação que a Claude API retorna, e trate erros com as exceções tipadas do SDK. --- ## Erros HTTP A API segue um formato previsível de códigos de erro HTTP: * 400 - `invalid_request_error`: Houve um problema com o formato ou o conteúdo da sua solicitação. Esse tipo de erro também pode ser usado para outros códigos de status 4XX não listados nesta seção. A API também retorna um 400 quando o uso atinge um [limite de gastos definido por você](https://platform.claude.com/docs/pt-BR/api/rate-limits#setting-your-own-spend-limit) para a organização ou o workspace, exceto limites no [workspace do Claude Code](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#claude-code-workspace), que podem retornar um 429 em vez disso. * 401 - `authentication_error`: Há um problema com sua ["API key" (chave de API)](https://platform.claude.com/docs/pt-BR/get-api-key) (por exemplo, ela está malformada, revogada ou expirada; consulte [Expiração de chaves](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-expiration)). No Claude Platform on AWS, isso também pode indicar um problema com suas credenciais da AWS ou com a assinatura SigV4. * 402 - `billing_error`: Há um problema com suas informações de cobrança ou pagamento. Verifique seus dados de pagamento no [Claude Console](https://platform.claude.com) ou no AWS Marketplace, se você estiver usando o Claude Platform on AWS. * 403 - `permission_error`: Sua chave de API não tem permissão para usar o recurso especificado. Verifique o acesso da sua organização e as configurações do workspace no [Claude Console](https://platform.claude.com). * 404 - `not_found_error`: O recurso solicitado não foi encontrado. Verifique o caminho do endpoint e quaisquer IDs de recurso na URL da solicitação. * 409 - `conflict_error`: A solicitação entra em conflito com o estado atual de um recurso. Por exemplo, o recurso foi modificado simultaneamente, ou um valor que deve ser único já está em uso. Resolva o conflito e, em seguida, tente a solicitação novamente. * 413 - `request_too_large`: A solicitação excede o número máximo de bytes permitido. Consulte [Limites de tamanho de solicitação](https://platform.claude.com/docs/pt-BR/api/errors#request-size-limits) para os máximos por endpoint. * 429 - `rate_limit_error`: Sua organização atingiu um ["rate limit" (limite de taxa)](https://platform.claude.com/docs/pt-BR/api/rate-limits), atingiu o teto de gastos mensal do seu nível de uso ou atingiu um limite de gastos no workspace do Claude Code. Um 429 por teto de gastos do nível não tem o cabeçalho `retry-after` e continua falhando até que o acesso seja retomado; consulte [Atingindo seu teto de gastos](https://platform.claude.com/docs/pt-BR/api/rate-limits#reaching-your-spend-cap) para saber como reconhecê-lo. * 500 - `api_error`: Ocorreu um erro inesperado nos sistemas internos da Anthropic. Tente a solicitação novamente com "exponential backoff" (recuo exponencial); se o erro persistir, entre em contato com o suporte informando o ["request ID" (ID da solicitação)](https://platform.claude.com/docs/pt-BR/api/errors#request-id). * 504 - `timeout_error`: A solicitação atingiu o tempo limite durante o processamento. Considere usar a [Messages API com streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) para solicitações de longa duração. Consulte [Solicitações longas](https://platform.claude.com/docs/pt-BR/api/errors#long-requests) para mais opções. * 529 - `overloaded_error`: A API está temporariamente sobrecarregada. Erros 529 podem ocorrer quando a API enfrenta tráfego elevado entre todos os usuários. Em casos raros, se sua organização tiver um aumento acentuado de uso, você poderá ver erros 429 devido a limites de aceleração na API. Para evitar atingir os limites de aceleração, aumente seu tráfego gradualmente e mantenha padrões de uso consistentes. O SDK oficial repete automaticamente falhas transitórias (como erros de conexão, limites de taxa e erros de servidor 5xx) com recuo exponencial, duas vezes por padrão, respeitando o cabeçalho `retry-after` quando presente. O cliente do SDK aceita `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`) para configurar ou desativar esse comportamento. Ao receber uma resposta de [streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) por "server-sent events" (eventos enviados pelo servidor), ou SSE, um erro pode ocorrer depois que a API retorna uma resposta 200. Nesse caso, o tratamento de erros não segue esses mecanismos padrão. Consulte [Eventos de erro](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming#error-events) para o formato dos erros no meio do stream. ## Limites de tamanho de solicitação A API impõe limites de tamanho às solicitações: | Tipo de endpoint | Tamanho máximo da solicitação | | -------------------------------------------------------------------------------------- | ----------------------------- | | Messages API | 32 MB | | Token Counting API | 32 MB | | [Batch API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) | 256 MB | | [Files API](https://platform.claude.com/docs/pt-BR/build-with-claude/files) | 500 MB | Se você exceder esses limites, receberá um erro 413 `request_too_large`. Na Claude API direta, o Cloudflare retorna esse erro antes que a solicitação chegue aos servidores da API. ## Formatos de erro A API sempre retorna erros em JSON, com um objeto `error` de nível superior que sempre inclui os valores `type` e `message`. A resposta também inclui um campo `request_id` para facilitar o rastreamento e a depuração. Por exemplo: ```json JSON { "type": "error", "error": { "type": "not_found_error", "message": "The requested resource could not be found." }, "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" } ``` De acordo com a política de [versionamento](https://platform.claude.com/docs/pt-BR/api/versioning), os valores dentro desses objetos podem ser ampliados, e é possível que novos valores de `type` sejam adicionados ao longo do tempo. ## Tipos de erro do SDK O SDK oficial lança exceções tipadas para esses erros em vez de retornar JSON bruto. Por exemplo, um 404 aparece como `anthropic.NotFoundError` (typescript: `Anthropic.NotFoundError`; ruby: `Anthropic::Errors::NotFoundError`; java: `com.anthropic.errors.NotFoundException`; csharp: `AnthropicNotFoundException`; php: `Anthropic\Core\Exceptions\NotFoundException`; go: `*anthropic.Error`). O SDK de Go tem um único tipo de erro para todos os status, `*anthropic.Error`: verifique `StatusCode` para diferenciá-los. Capture as classes tipadas do SDK em vez de comparar strings das mensagens de erro, tratando primeiro as classes mais específicas. A página do seu SDK documenta a hierarquia completa de exceções: * [Python](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/ruby#handling-errors) ## ID da solicitação Toda resposta da API inclui um cabeçalho `request-id` exclusivo, que contém um valor como `req_018EeWyXxfu5pfWkrYcMdjWG`. O mesmo identificador aparece como o campo `request_id` nos [corpos das respostas de erro](https://platform.claude.com/docs/pt-BR/api/errors#error-shapes). Ao entrar em contato com o suporte sobre uma solicitação específica, inclua esse ID para ajudar a resolver seu problema rapidamente. No [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), as respostas incluem dois IDs de solicitação. O principal é o ID de solicitação da AWS (`x-amzn-requestid`), indexado no CloudTrail. O secundário é o ID de solicitação da Anthropic (`request-id`). Use o ID de solicitação da AWS para consultas no CloudTrail e o ID de solicitação da Anthropic para tickets de suporte da Anthropic. Os SDKs de Python e TypeScript expõem o ID da solicitação como uma propriedade `_request_id` nos objetos de resposta de nível superior. Os SDKs de C#, Go, Java e PHP o expõem por meio de seus acessores de resposta bruta, e o SDK de Ruby, por meio de [middleware](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/middleware). Em todos os SDKs, exceto o de Ruby, use `with_raw_response` (typescript: `.withResponse()`; java: `.withRawResponse()`; csharp: `WithRawResponse`; go: `option.WithResponseInto`; php: `->raw`) para ler qualquer outro [cabeçalho de resposta](https://platform.claude.com/docs/pt-BR/api/overview#response-headers), como `anthropic-organization-id` e [`anthropic-workspace-id`](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). Em Ruby, use o mesmo middleware. No Claude Platform on AWS, use também o acessor de resposta bruta para ler o ID de solicitação da AWS (`x-amzn-requestid`): ```bash cURL # Imprime os cabeçalhos da resposta (incluindo request-id); descarta o corpo curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` ```bash CLI # O cabeçalho request-id é impresso no stderr com --debug: ant --debug messages create \ --model claude-sonnet-5 \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` ```python Python client = anthropic.Anthropic() message = client.messages.create( model="claude-sonnet-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello, Claude"}], ) print(f"Request ID: {message._request_id}") ``` ```typescript TypeScript const client = new Anthropic(); const message = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }); console.log("Request ID:", message._request_id); ``` ```csharp C# AnthropicClient client = new(); using var response = await client.WithRawResponse.Messages.Create(new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Hello, Claude" }] }); Console.WriteLine($"Request ID: {response.RequestID}"); ``` ```go Go client := anthropic.NewClient() var response *http.Response _, err := client.Messages.New( context.Background(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }, option.WithResponseInto(&response), ) if err != nil { panic(err) } fmt.Println("Request ID:", response.Header.Get("request-id")) ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.http.HttpResponseFor; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); HttpResponseFor response = client.messages().withRawResponse().create( MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(1024) .addUserMessage("Hello, Claude") .build() ); IO.println("Request ID: " + response.requestId().orElse(null)); } ``` ```php PHP $client = new Client(); $response = $client->messages->raw->create([ 'model' => 'claude-sonnet-5', 'maxTokens' => 1024, 'messages' => [['role' => 'user', 'content' => 'Hello, Claude']], ]); echo 'Request ID: ' . $response->getHeaderLine('request-id') . "\n"; ``` ```ruby Ruby client = Anthropic::Client.new # Leia os cabeçalhos de resposta no middleware por requisição, que recebe a # resposta HTTP bruta antes de o SDK analisá-la request_id = nil read_request_id = lambda do |request, call_next| response = call_next.call(request) # As chaves em response.headers estão em minúsculas request_id = response.headers["request-id"] response end client.messages.create( model: Anthropic::Model::CLAUDE_SONNET_5, max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }], request_options: { middleware: [read_request_id] } ) puts "Request ID: #{request_id}" ``` ```python Python (Claude Platform on AWS) from anthropic import AnthropicAWS client = AnthropicAWS(aws_region="us-west-2") response = client.messages.with_raw_response.create( model="claude-opus-5-5", max_tokens=1024, messages=[{"role": "user", "content": "Hello, Claude"}], ) print(f"AWS request ID: {response.headers.get('x-amzn-requestid')}") message = response.parse() print(f"Anthropic request ID: {message._request_id}") ``` ```typescript TypeScript (Claude Platform on AWS) import AnthropicAws from "@anthropic-ai/aws-sdk"; const client = new AnthropicAws({ awsRegion: "us-west-2" }); const { response: raw, request_id } = await client.messages .create({ model: "claude-opus-5-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }) .withResponse(); console.log("AWS request ID:", raw.headers.get("x-amzn-requestid")); console.log("Anthropic request ID:", request_id); ``` Para exemplos de IDs de solicitação do Claude Platform on AWS em outras linguagens, consulte [IDs de solicitação](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#request-ids). ## Solicitações longas Considere usar a [Messages API com streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) ou a [Message Batches API](https://platform.claude.com/docs/pt-BR/api/messages/batches/create) para solicitações de longa duração, especialmente aquelas com mais de 10 minutos. Evite definir um valor alto de `max_tokens` sem usar a [Messages API com streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming) ou a [Message Batches API](https://platform.claude.com/docs/pt-BR/api/messages/batches/create): * Algumas redes podem encerrar conexões ociosas após um período de tempo variável, o que pode fazer com que a solicitação falhe ou atinja o tempo limite sem receber uma resposta da Anthropic. * As redes diferem em confiabilidade. A [Message Batches API](https://platform.claude.com/docs/pt-BR/api/messages/batches/create) pode ajudar você a gerenciar o risco de problemas de rede, permitindo que você consulte os resultados periodicamente em vez de exigir uma conexão de rede ininterrupta. Se você estiver criando uma integração direta com a API, definir um ["TCP socket keep-alive" (manutenção de conexão do socket TCP)](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html) pode reduzir o impacto dos tempos limite de conexões ociosas em algumas redes. Os [SDKs](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) validam que suas solicitações sem streaming à Messages API não devem exceder um tempo limite de 10 minutos. Eles também definem uma opção de socket para keep-alive TCP. Se você não precisa processar eventos incrementalmente, o SDK pode consumir o stream por você e retornar o objeto `Message` completo, idêntico ao que uma chamada sem streaming retorna: Uma solicitação curl imprime os eventos brutos do stream e não consegue combiná-los na mensagem final. Para obter o objeto `Message` completo a partir de um stream, use o [Claude SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview). ```bash CLI # A CLI faz streaming de eventos; --format jsonl emite um evento por linha ant messages create --stream --format jsonl <<'YAML' model: claude-sonnet-5 max_tokens: 128000 messages: - role: user content: Write a detailed analysis... YAML ``` ```python Python client = anthropic.Anthropic() with client.messages.stream( max_tokens=128000, messages=[{"role": "user", "content": "Write a detailed analysis..."}], model="claude-sonnet-5", ) as stream: message = stream.get_final_message() print(next(block.text for block in message.content if block.type == "text")) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }], model: "claude-sonnet-5" }); const message = await stream.finalMessage(); const textBlock = message.content.find((block) => block.type === "text"); if (textBlock && textBlock.type === "text") { console.log(textBlock.text); } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 128000, Messages = [new() { Role = Role.User, Content = "Write a detailed analysis..." }] }; var message = await client.Messages.CreateStreaming(parameters).Aggregate(); Console.WriteLine(message); ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 128000, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Write a detailed analysis...")), }, }) message := anthropic.Message{} for stream.Next() { event := stream.Current() if err := message.Accumulate(event); err != nil { log.Fatal(err) } } if err := stream.Err(); err != nil { log.Fatal(err) } for _, block := range message.Content { if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok { fmt.Println(textBlock.Text) break } } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.helpers.MessageAccumulator; import com.anthropic.models.messages.ContentBlock; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(128000L) .addUserMessage("Write a detailed analysis...") .build(); MessageAccumulator accumulator = MessageAccumulator.create(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(accumulator::accumulate); } Message message = accumulator.message(); message.content().stream() .filter(ContentBlock::isText) .findFirst() .flatMap(ContentBlock::text) .ifPresent(textBlock -> IO.println(textBlock.text())); } ``` ```php PHP use Anthropic\Lib\Streaming\MessageAccumulator; $client = new Client(); $stream = $client->messages->createStream( model: 'claude-sonnet-5', maxTokens: 128000, messages: [['role' => 'user', 'content' => 'Write a detailed analysis...']], ); $accumulator = MessageAccumulator::forMessages(); foreach ($stream as $event) { $accumulator->accumulate($event); } echo array_find($accumulator->message()->content, static fn ($block): bool => $block->type === 'text')->text; ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.stream( model: "claude-sonnet-5", max_tokens: 128000, messages: [{ role: "user", content: "Write a detailed analysis..." }] ).accumulated_message puts message.content.find { it.type == :text }.text ``` Consulte [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming#get-the-final-message-without-handling-events) para mais detalhes. ## Erros de validação comuns ### Prefill não suportado Os modelos Claude 4.6 e posteriores e o [Claude Mythos Preview](https://anthropic.com/glasswing) não oferecem suporte a "prefill" (preenchimento prévio) de mensagens do assistente. Enviar uma solicitação com uma última mensagem do assistente preenchida previamente para qualquer um desses modelos retorna um 400 `invalid_request_error`: ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "This model does not support assistant message prefill. The conversation must end with a user message." } } ``` Em vez disso, use [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) nos modelos que oferecem suporte a elas, instruções no "system prompt" (prompt do sistema) ou [`output_config.format`](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs#usage). ### Blocos de pensamento não podem ser modificados Se a mensagem mais recente do assistente contiver blocos `thinking` ou `redacted_thinking` que foram editados, reordenados, filtrados ou reconstruídos antes de serem enviados de volta à API, a solicitação retornará um 400 `invalid_request_error`. A mensagem de erro começa com a posição do bloco problemático (por exemplo, `messages.1.content.0`) e contém: ```text wrap `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response. ``` Com "tool use" (uso de ferramentas), todos os blocos `thinking` e `redacted_thinking` do turno do assistente devem ser enviados de volta exatamente como foram recebidos, inclusive os blocos cujo campo `thinking` está vazio. Envie os blocos de pensamento de volta sem alterações. Se sua aplicação filtrar os blocos de conteúdo por tipo antes de reenviá-los, inclua tanto `thinking` quanto `redacted_thinking`. Consulte [Solução de problemas de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified), [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks) e [Pensamento preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserved-thinking). ### Pensamento estendido não suportado Os modelos Claude 4.7 e posteriores não têm mais "extended thinking" (pensamento estendido). Enviar `thinking: {"type": "enabled"}` a qualquer um desses modelos retorna um 400 `invalid_request_error`: ```text wrap "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` Em vez disso, use o ["adaptive thinking" (pensamento adaptativo)](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking). [Migrando para o pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#migrating-to-adaptive-thinking) mostra o mapeamento dos parâmetros, e [Solução de problemas de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled) apresenta a correção a partir do sintoma. ### Pensamento adaptativo não suportado Os modelos que oferecem suporte apenas ao pensamento estendido (Claude 4.5 e modelos anteriores) rejeitam `thinking: {"type": "adaptive"}` com um 400 `invalid_request_error`: ```text wrap adaptive thinking is not supported on this model ``` Nesses modelos, use `thinking: {"type": "enabled", "budget_tokens": N}`. Consulte [Pensamento estendido](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking) para ver a configuração e [Solução de problemas de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive) para a correção a partir do sintoma. ### O pensamento não pode ser desativado No Claude Fable 5.1, no [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview), no Claude Fable 5, no [Claude Mythos 5](https://platform.claude.com/docs/pt-BR/models/mythos-5/overview), no Claude Opus 5.5 e no [Claude Mythos Preview](https://anthropic.com/glasswing), o pensamento está sempre ativado. Enviar `thinking: {"type": "disabled"}` para qualquer um desses modelos retorna um 400 `invalid_request_error`. Em todos esses modelos, exceto o Claude Mythos Preview, a mensagem diz: ```text wrap "thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` No Claude Mythos Preview, o único desses modelos que aceita pensamento estendido, a mensagem diz: ```text wrap "thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking. ``` No Claude Sonnet 5.5, o pensamento não pode ser definido como `disabled`. Use `thinking: {"type": "between_tools"}` para a configuração de pensamento mais baixa, que desativa o pensamento antecipado. Enviar `thinking: {"type": "disabled"}` retorna um 400 `invalid_request_error` com esta mensagem: ```text wrap To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks. ``` Com [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) `xhigh` ou `max`, uma solicitação com `between_tools` também retorna um 400 `invalid_request_error`. A mensagem diz que o pensamento está desativado porque `between_tools` não tem pensamento antecipado: ```text wrap output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. ``` Com `between_tools`, o esforço não pode mudar no meio da conversa: um `output_config.effort` por mensagem que difere do nível em vigor retorna um erro 400. O erro indica a posição da mensagem que definiu o novo nível: ```text wrap messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking. ``` O Claude Haiku 5.5 aceita `thinking: {"type": "disabled"}` e o submete aos mesmos dois limites de esforço que se aplicam a `between_tools`: com esforço `xhigh` ou `max`, ou com um `output_config.effort` por mensagem que difere do nível em vigor, a solicitação retorna um 400 `invalid_request_error` com a mensagem correspondente mostrada anteriormente. Em ambas as mensagens, "enable thinking" significa pensamento adaptativo: omita o campo `thinking` ou envie `thinking: {"type": "adaptive"}`. O Claude Sonnet 5.5 e o Claude Haiku 5.5 rejeitam `"enabled"` com um erro 400. Para variar o esforço por turno, use o pensamento adaptativo. Enviar `thinking: {"type": "between_tools"}` para qualquer modelo que não seja o Claude Sonnet 5.5 retorna um 400 `invalid_request_error`: ```text wrap "thinking.type.between_tools" is not supported for this model. ``` Para as correções, consulte [Solução de problemas de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools), que aborda os erros de `between_tools` e de esforço. Omita o parâmetro `thinking` e a solicitação será executada com pensamento adaptativo. Para manter o conteúdo do pensamento fora das respostas sem desativar o pensamento, defina `display: "omitted"` na configuração de pensamento. Consulte [Solução de problemas de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled). ### Uso forçado de ferramentas não suportado O Claude Opus 5.5, o Claude Sonnet 5.5, o Claude Fable 5.1 e o [Claude Mythos 5.1](https://platform.claude.com/docs/pt-BR/models/mythos-5-1/overview) não oferecem suporte ao uso forçado de ferramentas. Enviar `tool_choice: {"type": "any"}` ou `tool_choice: {"type": "tool", "name": "..."}` para qualquer um desses modelos, inclusive no [endpoint de contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting), retorna um 400 `invalid_request_error`: ```text wrap tool_choice: type "tool" and "any" are not supported for this model. ``` `tool_choice: {"type": "auto"}` (o padrão) e `{"type": "none"}` são aceitos. Use `auto` com [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) para manter as entradas das ferramentas válidas segundo o schema, ou [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs) quando você precisar que a própria resposta tenha um formato JSON fixo. Consulte [Forçando o uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#forcing-tool-use). ### Versão da ferramenta de uso do computador não suportada Na Claude API e no Google Cloud, o Claude Opus 5.5, o Claude Sonnet 5.5 e o Claude Haiku 5.5 suportam [uso do computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) apenas como o toolset `computer_toolset_20260801`. Nessas plataformas, enviar a qualquer um desses modelos uma entrada em `tools` do tipo anterior `computer_20251124` ou `computer_20250124`, com o cabeçalho beta dessa ferramenta, retorna um 400 `invalid_request_error`. A mensagem indica o tipo rejeitado e, em seguida, lista os tipos de ferramenta que o modelo aceita após `Did you mean one of`. Para o Claude Opus 5.5, ela começa com: ```text wrap 'claude-opus-5-5' does not support tool types: computer_20251124. ``` A API retorna a mesma mensagem para qualquer tipo de ferramenta definido pela Anthropic que o modelo solicitado não suporta. Declare `{"type": "computer_toolset_20260801"}` sem o cabeçalho beta e atualize o loop do seu agente conforme descrito em [Migrar de `computer_20251124`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124). Para migrar de `computer_20250124`, consulte [Migre o uso de computador para o toolset](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#computer-use-toolset) no guia de migração do Claude Haiku 5.5. Modelos anteriores que suportam o toolset continuam aceitando `computer_20251124`, assim como o Claude Opus 5.5, o Claude Sonnet 5.5 e o Claude Haiku 5.5 no Amazon Bedrock. ### O bloco de pensamento não corresponde mais à conversa No Claude Fable 5.1, no Claude Opus 5.5, no Claude Sonnet 5.5 e no Claude Haiku 5.5, a API aceita um bloco de pensamento reenviado apenas enquanto o prompt `system`, as `tools` e as mensagens que o precederam permanecerem inalterados. Para novas contas criadas a partir de 31 de agosto de 2026, e para qualquer solicitação que defina `thinking.block_binding.prefix_mismatch_behavior` como `"error"`, um bloco reenviado cujo histórico anterior foi alterado é rejeitado com um 400 `invalid_request_error` (com `"drop_block"`, a API descarta o bloco e a solicitação é bem-sucedida). A mensagem começa com a posição do primeiro bloco com falha: ```text wrap messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". ``` Sem o cabeçalho beta `thinking-binding-controls-2026-08-01`, a mensagem também menciona esse cabeçalho. Mantenha o histórico da conversa apenas com acréscimos, ou envie o cabeçalho beta com `prefix_mismatch_behavior: "drop_block"` para descartar o bloco e continuar. No Claude Sonnet 5.5 e no Claude Haiku 5.5, `block_binding` funciona apenas com `thinking: {"type": "adaptive"}`. Com `between_tools` no Claude Sonnet 5.5, ou `thinking: {"type": "disabled"}` no Claude Haiku 5.5, mantenha o histórico apenas com acréscimos, ou remova os blocos de pensamento a partir do turno editado. Um bloco de um modelo que o modelo de destino não consegue ler é descartado em vez de rejeitado. Consulte [Manter o prefixo inalterado](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#prefix-check) e [Solução de problemas de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-block-signature). Enviar `thinking.block_binding` sem o [cabeçalho beta](https://platform.claude.com/docs/pt-BR/api/beta-headers) `thinking-binding-controls-2026-08-01` retorna um 400 `invalid_request_error` cuja mensagem termina com: ```text wrap block_binding: Extra inputs are not permitted ``` Adicione o cabeçalho ou remova o campo. ### Federação de identidade web de saída desativada (Claude Platform on AWS) Se todas as solicitações ao [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) retornarem `"Outbound web identity federation is disabled for your account"`, execute `aws iam enable-outbound-web-identity-federation` uma vez por conta da AWS. Consulte [Ativar a federação de identidade web de saída](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) para mais detalhes. ## Próximos passos Correções a partir do sintoma para erros 400 de configuração de pensamento, blocos de pensamento vazios e interrupções por `max_tokens`. Para reduzir o uso indevido e gerenciar a capacidade da API, há limites para o quanto uma organização pode usar a Claude API. Faça streaming incremental das respostas da Messages API com server-sent events, incluindo deltas de texto, de uso de ferramentas e de pensamento estendido.