---
title: Motivos de parada e fallback
url: https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons
description: Saiba o que cada valor de stop_reason significa e como lidar com truncamento, uso de ferramentas, turnos pausados e recusas na sua aplicação.
---

Toda resposta da Messages API inclui um campo [`stop_reason`](https://platform.claude.com/docs/pt-BR/api/messages/create#message.stop_reason) que informa por que Claude parou de gerar. Verifique esse campo para decidir se deve usar a resposta como está, continuar a conversa, tentar novamente ou fazer fallback para outro modelo.

Para o esquema completo da resposta, consulte a [referência da Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create).

## Referência rápida

| Valor                                                                                                                                           | Quando ocorre                                                      | O que fazer                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`end_turn`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#end-turn)                                           | Claude concluiu sua resposta naturalmente.                         | Use a resposta.                                                                                                                                            |
| [`max_tokens`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#max-tokens)                                       | A resposta atingiu seu limite de `max_tokens`.                     | Aumente `max_tokens` ou [continue a resposta](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#ensuring-complete-responses). |
| [`stop_sequence`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#stop-sequence)                                 | Claude emitiu uma das suas `stop_sequences`.                       | Leia `stop_sequence` para ver qual foi acionada.                                                                                                           |
| [`tool_use`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use)                                           | Claude está chamando uma ferramenta.                               | Execute a ferramenta e retorne o resultado. Uma chamada de ferramenta de servidor ainda sem seu bloco de resultado é concluída em uma resposta posterior.  |
| [`pause_turn`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#pause-turn)                                       | Um loop de ferramenta de servidor atingiu seu limite de iterações. | Envie o conteúdo do assistente de volta para continuar.                                                                                                    |
| [`refusal`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#refusal)                                             | Claude se recusou a responder.                                     | Leia `stop_details` e [tente novamente em um modelo de fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback).          |
| [`model_context_window_exceeded`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#model-context-window-exceeded) | A resposta preencheu a janela de contexto do modelo.               | Trate a resposta como truncada.                                                                                                                            |

## O campo stop\_reason

O campo `stop_reason` faz parte de toda resposta bem-sucedida da Messages API. Diferentemente dos erros, que indicam falhas no processamento da sua requisição, `stop_reason` informa por que Claude concluiu a geração da resposta.

```json Example response
{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}
```

## Valores de motivo de parada

### end\_turn

O motivo de parada mais comum. Indica que Claude concluiu sua resposta naturalmente.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello!"}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello!"}],
  )
  if response.stop_reason == "end_turn":
      # Processa a resposta completa
      for block in response.content:
          if block.type == "text":
              print(block.text)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }]
  });

  if (response.stop_reason === "end_turn") {
    // Processa a resposta completa
    const textBlock = response.content.find((block) => block.type === "text");
    console.log(textBlock?.text);
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Messages = [new UserMessageParam { Content = "Hello!" }]
  });

  if (response.StopReason == "end_turn")
  {
      // Processa a resposta completa
      foreach (var block in response.Content)
      {
          if (block.TryPickText(out var textBlock))
          {
              Console.WriteLine(textBlock.Text);
          }
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == "end_turn" {
  	// Processa a resposta completa
  	for _, block := range response.Content {
  		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  			fmt.Println(textBlock.Text)
  		}
  	}
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addUserMessage("Hello!")
          .build()
  );

  if (response.stopReason().map(StopReason.END_TURN::equals).orElse(false)) {
      // Processa a resposta completa
      response.content().stream()
          .flatMap(block -> block.text().stream())
          .forEach(textBlock -> IO.println(textBlock.text()));
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello!']],
      model: 'claude-opus-5-5',
  );

  if ($response->stopReason === 'end_turn') {
      // Processa a resposta completa
      foreach ($response->content as $block) {
          if ($block->type === 'text') {
              echo $block->text, PHP_EOL;
          }
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }]
  )

  if response.stop_reason == :end_turn
    # Processa a resposta completa
    response.content.each do |block|
      puts block.text if block.type == :text
    end
  end
  ```
</CodeGroup>

<Accordion title="Respostas vazias com end_turn">
  Às vezes Claude retorna uma resposta vazia (exatamente 2–3 tokens sem conteúdo) com `stop_reason: "end_turn"`. Isso normalmente ocorre quando Claude determina que o turno do assistente está completo, particularmente após resultados de ferramentas.

  **Causas comuns:**

  * Adicionar blocos de texto imediatamente após resultados de ferramentas (o histórico passa a mostrar texto do usuário após cada resultado de ferramenta, então Claude encerra seu turno para seguir esse padrão)
  * Enviar a resposta concluída de Claude de volta sem adicionar nada (Claude já determinou que terminou, então permanecerá assim)

  **Como evitar respostas vazias:**

  <CodeGroup exclude="shell">
    ```python Python
    # INCORRETO: adicionar texto imediatamente após tool_result
    messages = [
        {"role": "user", "content": "Calculate the sum of 1234 and 5678"},
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "toolu_123",
                    "name": "calculator",
                    "input": {"operation": "add", "a": 1234, "b": 5678},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"},
                {
                    "type": "text",
                    "text": "Here's the result",  # Don't add text after tool_result
                },
            ],
        },
    ]

    # CORRETO: enviar os resultados das ferramentas diretamente, sem texto adicional
    messages = [
        {"role": "user", "content": "Calculate the sum of 1234 and 5678"},
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "toolu_123",
                    "name": "calculator",
                    "input": {"operation": "add", "a": 1234, "b": 5678},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "tool_result", "tool_use_id": "toolu_123", "content": "6912"}
            ],
        },  # Only the tool_result, no additional text
    ]
    ```

    ```typescript TypeScript
    // INCORRETO: Adicionar texto imediatamente após tool_result
    let messages: Anthropic.MessageParam[] = [
      { role: "user", content: "Calculate the sum of 1234 and 5678" },
      {
        role: "assistant",
        content: [
          {
            type: "tool_use",
            id: "toolu_123",
            name: "calculator",
            input: { operation: "add", a: 1234, b: 5678 }
          }
        ]
      },
      {
        role: "user",
        content: [
          { type: "tool_result", tool_use_id: "toolu_123", content: "6912" },
          { type: "text", text: "Here's the result" } // Don't add text after tool_result
        ]
      }
    ];

    // CORRETO: Enviar resultados de ferramentas diretamente, sem texto adicional
    messages = [
      { role: "user", content: "Calculate the sum of 1234 and 5678" },
      {
        role: "assistant",
        content: [
          {
            type: "tool_use",
            id: "toolu_123",
            name: "calculator",
            input: { operation: "add", a: 1234, b: 5678 }
          }
        ]
      },
      {
        role: "user",
        // Apenas o tool_result, sem texto adicional
        content: [{ type: "tool_result", tool_use_id: "toolu_123", content: "6912" }]
      }
    ];
    ```

    ```csharp C#
    using System.Text.Json;
    using Anthropic.Models.Messages;

    var input = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
        """{"operation":"add","a":1234,"b":5678}"""
    )!;

    // INCORRETO: adicionar texto imediatamente após tool_result
    List<MessageParam> messages =
    [
        new UserMessageParam { Content = "Calculate the sum of 1234 and 5678" },
        new AssistantMessageParam
        {
            Content = new List<ContentBlockParam>
            {
                new ToolUseBlockParam { ID = "toolu_123", Name = "calculator", Input = input }
            }
        },
        new UserMessageParam
        {
            Content = new List<ContentBlockParam>
            {
                new ToolResultBlockParam { ToolUseID = "toolu_123", Content = "6912" },
                new TextBlockParam { Text = "Here's the result" } // Don't add text after tool_result
            }
        }
    ];

    // CORRETO: enviar os resultados das ferramentas diretamente, sem texto adicional
    messages =
    [
        new UserMessageParam { Content = "Calculate the sum of 1234 and 5678" },
        new AssistantMessageParam
        {
            Content = new List<ContentBlockParam>
            {
                new ToolUseBlockParam { ID = "toolu_123", Name = "calculator", Input = input }
            }
        },
        new UserMessageParam
        {
            // Apenas o tool_result, sem texto adicional
            Content = new List<ContentBlockParam>
            {
                new ToolResultBlockParam { ToolUseID = "toolu_123", Content = "6912" }
            }
        }
    ];
    ```

    ```go Go
    input := map[string]any{"operation": "add", "a": 1234, "b": 5678}

    // INCORRETO: Adicionar texto imediatamente após tool_result
    messages := []anthropic.MessageParam{
    	anthropic.NewUserMessage(anthropic.NewTextBlock("Calculate the sum of 1234 and 5678")),
    	anthropic.NewAssistantMessage(
    		anthropic.NewToolUseBlock("toolu_123", input, "calculator"),
    	),
    	anthropic.NewUserMessage(
    		anthropic.NewToolResultBlock("toolu_123", "6912", false),
    		anthropic.NewTextBlock("Here's the result"), // Don't add text after tool_result
    	),
    }

    // CORRETO: Enviar os resultados das ferramentas diretamente, sem texto adicional
    messages = []anthropic.MessageParam{
    	anthropic.NewUserMessage(anthropic.NewTextBlock("Calculate the sum of 1234 and 5678")),
    	anthropic.NewAssistantMessage(
    		anthropic.NewToolUseBlock("toolu_123", input, "calculator"),
    	),
    	// Apenas o tool_result, sem texto adicional
    	anthropic.NewUserMessage(
    		anthropic.NewToolResultBlock("toolu_123", "6912", false),
    	),
    }
    ```

    ```java Java
    ToolUseBlockParam toolUse = ToolUseBlockParam.builder()
        .id("toolu_123")
        .name("calculator")
        .input(ToolUseBlockParam.Input.builder()
            .putAdditionalProperty("operation", JsonValue.from("add"))
            .putAdditionalProperty("a", JsonValue.from(1234))
            .putAdditionalProperty("b", JsonValue.from(5678))
            .build())
        .build();

    // INCORRETO: Adicionar texto imediatamente após tool_result
    List<MessageParam> messages = List.of(
        MessageParam.ofUser("Calculate the sum of 1234 and 5678"),
        MessageParam.ofAssistantOfContentBlockParams(List.of(ContentBlockParam.ofToolUse(toolUse))),
        MessageParam.ofUserOfContentBlockParams(List.of(
            ContentBlockParam.ofToolResult(
                ToolResultBlockParam.builder()
                    .toolUseId("toolu_123")
                    .content("6912")
                    .build()),
            // Não adicione texto após tool_result
            ContentBlockParam.ofText(TextBlockParam.builder()
                .text("Here's the result")
                .build())
        ))
    );

    // CORRETO: Envie os resultados das ferramentas diretamente, sem texto adicional
    messages = List.of(
        MessageParam.ofUser("Calculate the sum of 1234 and 5678"),
        MessageParam.ofAssistantOfContentBlockParams(List.of(ContentBlockParam.ofToolUse(toolUse))),
        // Apenas o tool_result, sem texto adicional
        MessageParam.ofUserOfContentBlockParams(List.of(
            ContentBlockParam.ofToolResult(
                ToolResultBlockParam.builder()
                    .toolUseId("toolu_123")
                    .content("6912")
                    .build())
        ))
    );
    ```

    ```php PHP
    // INCORRETO: adicionar texto imediatamente após tool_result
    $messages = [
        ['role' => 'user', 'content' => 'Calculate the sum of 1234 and 5678'],
        [
            'role' => 'assistant',
            'content' => [
                [
                    'type' => 'tool_use',
                    'id' => 'toolu_123',
                    'name' => 'calculator',
                    'input' => ['operation' => 'add', 'a' => 1234, 'b' => 5678],
                ],
            ],
        ],
        [
            'role' => 'user',
            'content' => [
                ['type' => 'tool_result', 'tool_use_id' => 'toolu_123', 'content' => '6912'],
                // Não adicione texto após tool_result
                ['type' => 'text', 'text' => "Here's the result"],
            ],
        ],
    ];

    // CORRETO: enviar os resultados das ferramentas diretamente, sem texto adicional
    $messages = [
        ['role' => 'user', 'content' => 'Calculate the sum of 1234 and 5678'],
        [
            'role' => 'assistant',
            'content' => [
                [
                    'type' => 'tool_use',
                    'id' => 'toolu_123',
                    'name' => 'calculator',
                    'input' => ['operation' => 'add', 'a' => 1234, 'b' => 5678],
                ],
            ],
        ],
        [
            'role' => 'user',
            // Apenas o tool_result, sem texto adicional
            'content' => [
                ['type' => 'tool_result', 'tool_use_id' => 'toolu_123', 'content' => '6912'],
            ],
        ],
    ];
    ```

    ```ruby Ruby
    # INCORRETO: adicionar texto imediatamente após tool_result
    messages = [
      { role: "user", content: "Calculate the sum of 1234 and 5678" },
      {
        role: "assistant",
        content: [
          {
            type: "tool_use",
            id: "toolu_123",
            name: "calculator",
            input: { operation: "add", a: 1234, b: 5678 }
          }
        ]
      },
      {
        role: "user",
        content: [
          { type: "tool_result", tool_use_id: "toolu_123", content: "6912" },
          # Não adicione texto após tool_result
          { type: "text", text: "Here's the result" }
        ]
      }
    ]

    # CORRETO: enviar os resultados das ferramentas diretamente, sem texto adicional
    messages = [
      { role: "user", content: "Calculate the sum of 1234 and 5678" },
      {
        role: "assistant",
        content: [
          {
            type: "tool_use",
            id: "toolu_123",
            name: "calculator",
            input: { operation: "add", a: 1234, b: 5678 }
          }
        ]
      },
      {
        role: "user",
        # Apenas o tool_result, sem texto adicional
        content: [
          { type: "tool_result", tool_use_id: "toolu_123", content: "6912" }
        ]
      }
    ]
    ```
  </CodeGroup>

  Se você ainda receber respostas vazias após corrigir a estrutura das mensagens, adicione um prompt de continuação em uma nova mensagem do usuário em vez de tentar novamente com a resposta vazia:

  <CodeGroup exclude="shell">
    ```python Python
    def handle_empty_response(client, messages):
        response = client.messages.create(
            model="claude-opus-5-5", max_tokens=1024, messages=messages
        )

        # Verifica se a resposta está vazia
        if response.stop_reason == "end_turn" and not response.content:
            # INCORRETO: não tente novamente apenas com a resposta vazia
            # Isso não vai funcionar porque o Claude já decidiu que terminou

            # CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
            messages.append({"role": "user", "content": "Please continue"})

            response = client.messages.create(
                model="claude-opus-5-5", max_tokens=1024, messages=messages
            )

        return response
    ```

    ```typescript TypeScript
    async function handleEmptyResponse(
      client: Anthropic,
      messages: Anthropic.MessageParam[]
    ): Promise<Anthropic.Message> {
      let response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages
      });

      // Verifica se a resposta está vazia
      if (response.stop_reason === "end_turn" && response.content.length === 0) {
        // INCORRETO: não tente novamente apenas com a resposta vazia
        // Isso não funciona porque Claude já decidiu que terminou

        // CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
        messages.push({ role: "user", content: "Please continue" });

        response = await client.messages.create({
          model: "claude-opus-5-5",
          max_tokens: 1024,
          messages
        });
      }

      return response;
    }
    ```

    ```csharp C#
    static async Task<Message> HandleEmptyResponse(AnthropicClient client, List<MessageParam> messages)
    {
        var response = await client.Messages.Create(new MessageCreateParams
        {
            Model = Model.ClaudeOpus5_5,
            MaxTokens = 1024,
            Messages = messages
        });

        // Verifica se a resposta está vazia
        if (response.StopReason == "end_turn" && response.Content.Count == 0)
        {
            // CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
            messages.Add(new UserMessageParam { Content = "Please continue" });

            response = await client.Messages.Create(new MessageCreateParams
            {
                Model = Model.ClaudeOpus5_5,
                MaxTokens = 1024,
                Messages = messages
            });
        }

        return response;
    }
    ```

    ```go Go
    func handleEmptyResponse(client anthropic.Client, messages []anthropic.MessageParam) (*anthropic.Message, error) {
    	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
    		Model:     anthropic.ModelClaudeOpus5_5,
    		MaxTokens: 1024,
    		Messages:  messages,
    	})
    	if err != nil {
    		return nil, err
    	}

    	// Verifica se a resposta está vazia
    	if response.StopReason == "end_turn" && len(response.Content) == 0 {
    		// CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
    		messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Please continue")))

    		response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
    			Model:     anthropic.ModelClaudeOpus5_5,
    			MaxTokens: 1024,
    			Messages:  messages,
    		})
    		if err != nil {
    			return nil, err
    		}
    	}

    	return response, nil
    }
    ```

    ```java Java
    static Message handleEmptyResponse(AnthropicClient client, List<MessageParam> messages) {
        Message response = client.messages().create(
            MessageCreateParams.builder()
                .model(Model.CLAUDE_OPUS_5_5)
                .maxTokens(1024L)
                .messages(messages)
                .build()
        );

        // Verifica se a resposta está vazia
        boolean isEndTurn = response.stopReason().map(StopReason.END_TURN::equals).orElse(false);
        if (isEndTurn && response.content().isEmpty()) {
            // CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
            List<MessageParam> extended = new ArrayList<>(messages);
            extended.add(MessageParam.ofUser("Please continue"));

            response = client.messages().create(
                MessageCreateParams.builder()
                    .model(Model.CLAUDE_OPUS_5_5)
                    .maxTokens(1024L)
                    .messages(extended)
                    .build()
            );
        }

        return response;
    }
    ```

    ```php PHP
    function handle_empty_response(Client $client, array $messages)
    {
        $response = $client->messages->create(
            maxTokens: 1024,
            messages: $messages,
            model: 'claude-opus-5-5',
        );

        // Verifica se a resposta está vazia
        if ($response->stopReason === 'end_turn' && count($response->content) === 0) {
            // CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
            $messages[] = ['role' => 'user', 'content' => 'Please continue'];

            $response = $client->messages->create(
                maxTokens: 1024,
                messages: $messages,
                model: 'claude-opus-5-5',
            );
        }

        return $response;
    }
    ```

    ```ruby Ruby
    def handle_empty_response(client, messages)
      response = client.messages.create(
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: messages
      )

      # Verifica se a resposta está vazia
      if response.stop_reason == :end_turn && response.content.empty?
        # CORRETO: adicione um prompt de continuação em uma NOVA mensagem do usuário
        messages << { role: "user", content: "Please continue" }

        response = client.messages.create(
          model: "claude-opus-5-5",
          max_tokens: 1024,
          messages: messages
        )
      end

      response
    end
    ```
  </CodeGroup>

  **Melhores práticas:**

  1. **Nunca adicione blocos de texto imediatamente após resultados de ferramentas:** Isso estabelece um padrão de entrada do usuário após cada uso de ferramenta, e Claude segue esse padrão encerrando seu turno.
  2. **Não tente novamente respostas vazias sem modificação:** Enviar a resposta vazia de volta não ajudará.
  3. **Use prompts de continuação como último recurso:** Somente se essas correções não resolverem o problema.
</Accordion>

### max\_tokens

Claude parou porque atingiu o limite de [`max_tokens`](https://platform.claude.com/docs/pt-BR/api/messages/create#create.max_tokens) especificado na sua requisição.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 10,
      "messages": [{"role": "user", "content": "Explain quantum physics"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 10 \
    --message '{role: user, content: "Explain quantum physics"}'
  ```

  ```python Python
  client = anthropic.Anthropic()
  # Requisição com tokens limitados
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=10,
      messages=[{"role": "user", "content": "Explain quantum physics"}],
  )

  if response.stop_reason == "max_tokens":
      # A resposta foi truncada
      print("Response was cut off at token limit")
      # Considere fazer outra requisição para continuar
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Requisição com tokens limitados
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 10,
    messages: [{ role: "user", content: "Explain quantum physics" }]
  });

  if (response.stop_reason === "max_tokens") {
    // A resposta foi truncada
    console.log("Response was cut off at token limit");
    // Considere fazer outra requisição para continuar
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Requisição com tokens limitados
  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 10,
      Messages = [new UserMessageParam { Content = "Explain quantum physics" }]
  });

  if (response.StopReason == "max_tokens")
  {
      // A resposta foi truncada
      Console.WriteLine("Response was cut off at token limit");
      // Considere fazer outra requisição para continuar
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  // Requisição com tokens limitados
  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 10,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Explain quantum physics")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == "max_tokens" {
  	// A resposta foi truncada
  	fmt.Println("Response was cut off at token limit")
  	// Considere fazer outra requisição para continuar
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Requisição com tokens limitados
  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(10L)
          .addUserMessage("Explain quantum physics")
          .build()
  );

  if (response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
      // A resposta foi truncada
      IO.println("Response was cut off at token limit");
      // Considere fazer outra requisição para continuar
  }
  ```

  ```php PHP
  $client = new Client();

  // Requisição com tokens limitados
  $response = $client->messages->create(
      maxTokens: 10,
      messages: [['role' => 'user', 'content' => 'Explain quantum physics']],
      model: Model::CLAUDE_OPUS_5_5,
  );

  if ($response->stopReason === 'max_tokens') {
      // A resposta foi truncada
      echo 'Response was cut off at token limit', PHP_EOL;
      // Considere fazer outra requisição para continuar
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Requisição com tokens limitados
  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 10,
    messages: [{ role: "user", content: "Explain quantum physics" }]
  )

  if response.stop_reason == :max_tokens
    # A resposta foi truncada
    puts "Response was cut off at token limit"
    # Considere fazer outra requisição para continuar
  end
  ```
</CodeGroup>

<Accordion title="Blocos de uso de ferramentas incompletos">
  Se a resposta de Claude for cortada porque atingiu o limite de `max_tokens`, e a resposta truncada contiver um bloco de uso de ferramentas incompleto, você precisará repetir a requisição com um valor de `max_tokens` maior para obter o uso de ferramentas completo.

  <CodeGroup exclude="shell:cURL, shell:CLI">
    <CodeGroupItem language="cURL">
      Este fluxo de trabalho precisa de mais lógica do que um único comando de shell. Use o [Anthropic SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) para executá-lo.
    </CodeGroupItem>

    <CodeGroupItem language="CLI">
      Este fluxo de trabalho precisa de mais lógica do que um único comando de shell. Use o [Anthropic SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) para executá-lo.
    </CodeGroupItem>

    ```python Python
    # Verifica se a resposta foi truncada durante o uso de ferramentas
    if response.stop_reason == "max_tokens":
        # Verifica se o último bloco de conteúdo é um tool_use incompleto
        last_block = response.content[-1]
        if last_block.type == "tool_use":
            # Envia a requisição com um max_tokens maior
            response = client.messages.create(
                model="claude-opus-5-5",
                max_tokens=4096,  # Increased limit
                messages=messages,
                tools=tools,
            )
    ```

    ```typescript TypeScript
    // Verifica se a resposta foi truncada durante o uso de ferramentas
    if (response.stop_reason === "max_tokens") {
      // Verifica se o último bloco de conteúdo é um tool_use incompleto
      const lastBlock = response.content[response.content.length - 1];
      if (lastBlock.type === "tool_use") {
        // Envia a requisição com um max_tokens maior
        response = await client.messages.create({
          model: "claude-opus-5-5",
          max_tokens: 4096, // Increased limit
          messages: messages,
          tools: tools
        });
      }
    }
    ```

    ```csharp C#
    using System.Linq;
    using Anthropic;
    using Anthropic.Models.Messages;

    AnthropicClient client = new();

    var parameters = new MessageCreateParams
    {
        Model = Model.ClaudeOpus5_5,
        MaxTokens = 1024,
        Messages = messages,
        Tools = tools
    };

    var response = await client.Messages.Create(parameters);

    if (response.StopReason == "max_tokens")
    {
        var lastBlock = response.Content.Last();
        if (lastBlock.TryPickToolUse(out _))
        {
            response = await client.Messages.Create(parameters with { MaxTokens = 4096 });
        }
    }
    ```

    ```go Go
    response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
    	Model:     anthropic.ModelClaudeOpus5_5,
    	MaxTokens: 1024,
    	Messages:  messages,
    	Tools:     tools,
    })
    if err != nil {
    	log.Fatal(err)
    }

    if response.StopReason == "max_tokens" {
    	lastBlock := response.Content[len(response.Content)-1]
    	switch lastBlock.AsAny().(type) {
    	case anthropic.ToolUseBlock:
    		response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
    			Model:     anthropic.ModelClaudeOpus5_5,
    			MaxTokens: 4096,
    			Messages:  messages,
    			Tools:     tools,
    		})
    		if err != nil {
    			log.Fatal(err)
    		}
    	}
    }
    ```

    ```java Java
    // Verifica se a resposta foi truncada durante o uso de ferramentas
    if (response.stopReason().isPresent() && response.stopReason().get().equals(StopReason.MAX_TOKENS)) {
        ContentBlock lastBlock = response.content().get(response.content().size() - 1);
        if (lastBlock.toolUse().isPresent()) {
            // Envia a requisição com um max_tokens maior
            response = client.messages().create(
                MessageCreateParams.builder()
                    .model(Model.CLAUDE_OPUS_5_5)
                    .maxTokens(4096L) // Increased limit
                    .messages(messages)
                    .tools(tools)
                    .build()
            );
        }
    }
    ```

    ```php PHP
    $response = $client->messages->create(
        maxTokens: 1024,
        messages: $messages,
        model: 'claude-opus-5-5',
        tools: $tools,
    );

    if ($response->stopReason === 'max_tokens') {
        $lastBlock = end($response->content);
        if ($lastBlock->type === 'tool_use') {
            $response = $client->messages->create(
                maxTokens: 4096,
                messages: $messages,
                model: 'claude-opus-5-5',
                tools: $tools,
            );
        }
    }
    ```

    ```ruby Ruby
    response = client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 1024,
      messages: messages,
      tools: tools
    )

    if response.stop_reason == :max_tokens
      last_block = response.content.last
      if last_block.type == :tool_use
        response = client.messages.create(
          model: Anthropic::Model::CLAUDE_OPUS_5_5,
          max_tokens: 4096,
          messages: messages,
          tools: tools
        )
      end
    end
    ```
  </CodeGroup>
</Accordion>

### stop\_sequence

Claude encontrou uma das suas [sequências de parada](https://platform.claude.com/docs/pt-BR/api/messages/create#create.stop_sequences) personalizadas.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "stop_sequences": ["END", "STOP"],
      "messages": [{"role": "user", "content": "Generate text until you say END"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --stop-sequence END --stop-sequence STOP \
    --message '{role: user, content: "Generate text until you say END"}'
  ```

  ```python Python
  client = anthropic.Anthropic()
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      stop_sequences=["END", "STOP"],
      messages=[{"role": "user", "content": "Generate text until you say END"}],
  )

  if response.stop_reason == "stop_sequence":
      print(f"Stopped at sequence: {response.stop_sequence}")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    stop_sequences: ["END", "STOP"],
    messages: [{ role: "user", content: "Generate text until you say END" }]
  });

  if (response.stop_reason === "stop_sequence") {
    console.log(`Stopped at sequence: ${response.stop_sequence}`);
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      StopSequences = ["END", "STOP"],
      Messages = [new UserMessageParam { Content = "Generate text until you say END" }]
  });

  if (response.StopReason == "stop_sequence")
  {
      Console.WriteLine($"Stopped at sequence: {response.StopSequence}");
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:         anthropic.ModelClaudeOpus5_5,
  	MaxTokens:     1024,
  	StopSequences: []string{"END", "STOP"},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Generate text until you say END")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == "stop_sequence" {
  	fmt.Printf("Stopped at sequence: %s\n", response.StopSequence)
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addStopSequence("END")
          .addStopSequence("STOP")
          .addUserMessage("Generate text until you say END")
          .build()
  );

  if (response.stopReason().map(StopReason.STOP_SEQUENCE::equals).orElse(false)) {
      IO.println("Stopped at sequence: " + response.stopSequence().orElse(""));
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Generate text until you say END']],
      model: Model::CLAUDE_OPUS_5_5,
      stopSequences: ['END', 'STOP'],
  );

  if ($response->stopReason === 'stop_sequence') {
      echo "Stopped at sequence: {$response->stopSequence}", PHP_EOL;
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    stop_sequences: ["END", "STOP"],
    messages: [{ role: "user", content: "Generate text until you say END" }]
  )

  if response.stop_reason == :stop_sequence
    puts "Stopped at sequence: #{response.stop_sequence}"
  end
  ```
</CodeGroup>

### tool\_use

Claude está chamando uma ferramenta que você precisa executar.

<Note>
  Para a maioria das implementações de uso de ferramentas, use o [tool runner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner), que lida automaticamente com a execução de ferramentas, a formatação de resultados e o gerenciamento da conversa.
</Note>

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "tools": [{
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {"location": {"type": "string", "description": "City and state"}},
          "required": ["location"]
        }
      }],
      "messages": [{"role": "user", "content": "What is the weather in San Francisco?"}]
    }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 1024
  messages:
    - role: user
      content: What is the weather in San Francisco?
  tools:
    - name: get_weather
      description: Get the current weather in a given location
      input_schema:
        type: object
        properties:
          location: {type: string, description: City and state}
        required: [location]
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()
  weather_tool = {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
          "type": "object",
          "properties": {
              "location": {"type": "string", "description": "City and state"},
          },
          "required": ["location"],
      },
  }


  def execute_tool(name, tool_input):
      """Run a tool and return the result."""
      return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      tools=[weather_tool],
      messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
  )

  if response.stop_reason == "tool_use":
      # Extrai e executa a ferramenta
      for block in response.content:
          if block.type == "tool_use":
              result = execute_tool(block.name, block.input)
              # Retorna o resultado ao Claude para a resposta final
  ```

  ```typescript TypeScript
  const client = new Anthropic();
  const weatherTool: Anthropic.Tool = {
    name: "get_weather",
    description: "Get the current weather in a given location",
    input_schema: {
      type: "object",
      properties: {
        location: { type: "string", description: "City and state" }
      },
      required: ["location"]
    }
  };

  function executeTool(name: string, input: Record<string, string>): string {
    return `Weather in ${input.location ?? "unknown"}: 72°F`;
  }

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: [weatherTool],
    messages: [{ role: "user", content: "What is the weather in San Francisco?" }]
  });

  if (response.stop_reason === "tool_use") {
    // Extrai e executa a ferramenta
    for (const block of response.content) {
      if (block.type === "tool_use") {
        const result = executeTool(block.name, block.input as Record<string, string>);
        // Retorna o resultado ao Claude para a resposta final
      }
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var weatherTool = new Tool
  {
      Name = "get_weather",
      Description = "Get the current weather in a given location",
      InputSchema = new InputSchema
      {
          Properties = new Dictionary<string, JsonElement>
          {
              ["location"] = JsonSerializer.SerializeToElement(
                  new { type = "string", description = "City and state" }
              ),
          },
          Required = ["location"]
      }
  };

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Tools = [weatherTool],
      Messages = [new UserMessageParam { Content = "What is the weather in San Francisco?" }]
  });

  if (response.StopReason == "tool_use")
  {
      // Extrai e executa a ferramenta
      foreach (var block in response.Content)
      {
          if (block.TryPickToolUse(out var toolUse))
          {
              // Executa toolUse.Name com toolUse.Input e retorna o resultado para o Claude
          }
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  weatherTool := anthropic.ToolParam{
  	Name:        "get_weather",
  	Description: anthropic.String("Get the current weather in a given location"),
  	InputSchema: anthropic.ToolInputSchemaParam{
  		Properties: map[string]any{
  			"location": map[string]string{"type": "string", "description": "City and state"},
  		},
  		Required: []string{"location"},
  	},
  }

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Tools:     []anthropic.ToolUnionParam{{OfTool: &weatherTool}},
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == "tool_use" {
  	// Extrai e executa a ferramenta
  	for _, block := range response.Content {
  		if toolUse, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
  			fmt.Println(toolUse.Name, toolUse.Input)
  			// Retorna o resultado ao Claude para a resposta final
  		}
  	}
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  Tool weatherTool = Tool.builder()
      .name("get_weather")
      .description("Get the current weather in a given location")
      .inputSchema(Tool.InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "location", Map.of("type", "string", "description", "City and state")
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("location")))
          .build())
      .build();

  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addTool(weatherTool)
          .addUserMessage("What is the weather in San Francisco?")
          .build()
  );

  if (response.stopReason().map(StopReason.TOOL_USE::equals).orElse(false)) {
      // Extrai e executa a ferramenta
      for (ContentBlock block : response.content()) {
          block.toolUse().ifPresent(toolUse -> {
              // Executa toolUse.name() com toolUse.input() e retorna o resultado ao Claude
          });
      }
  }
  ```

  ```php PHP
  $client = new Client();

  $weatherTool = [
      'name' => 'get_weather',
      'description' => 'Get the current weather in a given location',
      'input_schema' => [
          'type' => 'object',
          'properties' => [
              'location' => ['type' => 'string', 'description' => 'City and state'],
          ],
          'required' => ['location'],
      ],
  ];

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'What is the weather in San Francisco?']],
      model: 'claude-opus-5-5',
      tools: [$weatherTool],
  );

  if ($response->stopReason === 'tool_use') {
      // Extrai e executa a ferramenta
      foreach ($response->content as $block) {
          if ($block->type === 'tool_use') {
              // Executa $block->name com $block->input e retorna o resultado para o Claude
          }
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  weather_tool = {
    name: "get_weather",
    description: "Get the current weather in a given location",
    input_schema: {
      type: "object",
      properties: {
        location: { type: "string", description: "City and state" }
      },
      required: ["location"]
    }
  }

  response = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    tools: [weather_tool],
    messages: [{ role: "user", content: "What is the weather in San Francisco?" }]
  )

  if response.stop_reason == :tool_use
    # Extrai e executa a ferramenta
    response.content.each do |block|
      next unless block.type == :tool_use
      # Executa block.name com block.input e retorna o resultado para o Claude
    end
  end
  ```
</CodeGroup>

#### Quando uma ferramenta de servidor ainda está aguardando

Claude pode chamar uma [ferramenta de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) e uma ferramenta de cliente (uma ferramenta que o seu código executa) no mesmo grupo de [chamadas de ferramentas paralelas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use). A API então retorna uma resposta `tool_use` sem executar a ferramenta de servidor para que você possa executar as ferramentas de cliente primeiro.

A chamada em espera é um bloco `server_tool_use` ou `mcp_tool_use` sem bloco de resultado. Nada mais na resposta a marca. Depois que uma ferramenta de servidor é executada, seu bloco de resultado, como `web_search_tool_result`, contém o `id` da chamada em seu campo `tool_use_id`.

<Note>
  Com a [chamada programática de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling), o mesmo formato de resposta significa algo diferente. O bloco `tool_use` de cliente vem de código que está sendo executado na ferramenta `code_execution`, e não diretamente de Claude, e seu campo `caller` indica o bloco `code_execution` que o chamou. Esse código já começou: ele está pausado aguardando seus blocos `tool_result`, e enviá-los retoma a execução em vez de iniciar uma ferramenta adiada. O próprio bloco de resultado do bloco `code_execution` chega quando o código é concluído, o que pode levar mais de uma rodada de resultados de ferramentas. A mensagem de acompanhamento do usuário em si é a mesma em ambos os casos; com a chamada programática de ferramentas, passe também de volta o `id` do campo `container` da resposta, como essa página mostra.
</Note>

Esta resposta mista tem uma ferramenta de servidor em espera e uma chamada de ferramenta de cliente:

```json A mixed tool_use response
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_search",
      "input": { "query": "example article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}
```

Para continuar a partir de uma resposta mista como esta, crie uma requisição de acompanhamento:

1. Mantenha as mensagens anteriores e adicione o `content` da resposta sem alterações como uma mensagem `assistant`.
2. Adicione uma mensagem de usuário que contenha apenas blocos `tool_result`, um para cada bloco `tool_use` de cliente. Uma chamada em espera não recebe nenhum.
3. Envie a requisição com o mesmo array `tools` de antes para que a ferramenta de servidor em espera continue definida.

Para os campos de um bloco `tool_result`, consulte [Lidar com chamadas de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls). A mensagem de usuário na requisição de acompanhamento tem esta aparência:

```json The follow-up user message
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}
```

A API adiciona seus resultados ao turno inacabado de Claude, executa a ferramenta de servidor em espera e continua. Para uma ferramenta de servidor que Claude chamou diretamente, o `content` da próxima resposta começa com o bloco de resultado dessa ferramenta.

Um loop que segue os passos anteriores para toda resposta `tool_use` não precisa detectar uma ferramenta de servidor em espera. Nas requisições posteriores, mantenha três mensagens separadas em `messages`, nesta ordem: a primeira resposta, sua mensagem `tool_result` e a próxima resposta.

Dois casos precisam de mais um campo na requisição de acompanhamento:

* **A resposta inclui um `container`:** Envie o ID dele de volta (consulte a seção [Reutilização de contêiner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse) da ferramenta de execução de código).
* **O bloco em espera é um [bloco `mcp_tool_use`](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#mcp-tool-use-block):** Envie os mesmos `mcp_servers` de antes.

Cada um destes erros na requisição de acompanhamento falha com um 400 `invalid_request_error`. As mensagens mostradas são para a pesquisa na web. Para outras ferramentas de servidor, os nomes nelas são diferentes.

| Erro                                                                                                | A mensagem de erro inclui                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `tools` não define mais a ferramenta de servidor em espera                                          | ``but no `web_search` tool was provided``                                      |
| Texto ou outro conteúdo vem após os blocos `tool_result`                                            | ``was found without a corresponding `web_search_tool_result` block``           |
| Com a chamada programática de ferramentas, texto ou outro conteúdo vem após os blocos `tool_result` | `only tool_result blocks are allowed`                                          |
| Texto ou outro conteúdo vem antes dos blocos `tool_result`                                          | `` `tool_use` ids were found without `tool_result` blocks immediately after `` |
| Um bloco `tool_result` está faltando                                                                | `` `tool_use` ids were found without `tool_result` blocks immediately after `` |

Conteúdo após os blocos `tool_result` falha porque encerra o turno de Claude enquanto a ferramenta de servidor ainda está aguardando. Para dar mais entrada a Claude, continue até que o `stop_reason` de uma resposta não seja `tool_use` nem `pause_turn`. Em seguida, envie a entrada como uma nova mensagem de usuário na mesma lista `messages`.

### pause\_turn

Retornado quando o loop de amostragem do lado do servidor atinge seu limite de iterações durante a execução de [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools), como a pesquisa na web. O limite padrão é de 10 iterações por solicitação.

Quando Claude para para chamar uma ferramenta que você executa, o motivo de parada é [`tool_use`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#tool-use), nunca `pause_turn`.

Para permitir que Claude conclua um turno pausado, crie uma nova requisição:

1. Mantenha as mensagens anteriores e adicione o `content` da resposta sem alterações como uma mensagem `assistant`, incluindo qualquer bloco `server_tool_use` que não tenha bloco de resultado.
2. Envie a requisição com as mesmas `tools` de antes e sem mensagem de usuário após a mensagem `assistant`.

Se a resposta incluir um `container`, envie também o ID dele de volta para que o turno mantenha seus arquivos. Para mais detalhes, consulte a seção [Reutilização de contêiner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse) da ferramenta de execução de código. Os exemplos a seguir usam a pesquisa na web e não enviam ID de contêiner:

<CodeGroup>
  ```bash cURL
  # Os SDKs tratam a continuação diretamente. Com cURL, inspecione stop_reason
  # na resposta e faça um novo POST com o conteúdo do assistente anexado.
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 4096,
      "tools": [{"type": "web_search_20250305", "name": "web_search"}],
      "messages": [{"role": "user", "content": "Search for latest AI news"}]
    }'
  ```

  ```bash CLI
  # Inspecione stop_reason; se for pause_turn, execute novamente com a resposta
  # do assistente anexada a --message.
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 4096
  tools:
    - {type: web_search_20250305, name: web_search}
  messages:
    - {role: user, content: "Search for latest AI news"}
  YAML
  ```

  ```python Python
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=4096,
      tools=[{"type": "web_search_20250305", "name": "web_search"}],
      messages=[{"role": "user", "content": "Search for latest AI news"}],
  )

  if response.stop_reason == "pause_turn":
      # Continue a conversa enviando a resposta de volta
      messages = [
          {"role": "user", "content": "Search for latest AI news"},
          {"role": "assistant", "content": response.content},
      ]
      continuation = client.messages.create(
          model="claude-opus-5-5",
          max_tokens=4096,
          messages=messages,
          tools=[{"type": "web_search_20250305", "name": "web_search"}],
      )
  ```

  ```typescript TypeScript
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    tools: [{ type: "web_search_20250305", name: "web_search" }],
    messages: [{ role: "user", content: "Search for latest AI news" }]
  });

  if (response.stop_reason === "pause_turn") {
    // Continue a conversa enviando a resposta de volta
    const continuation = await client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 4096,
      tools: [{ type: "web_search_20250305", name: "web_search" }],
      messages: [
        { role: "user", content: "Search for latest AI news" },
        { role: "assistant", content: response.content }
      ]
    });
  }
  ```

  ```csharp C#
  List<ToolUnion> tools = [new ToolUnion(new WebSearchTool20250305())];
  MessageParam userMessage = new UserMessageParam { Content = "Search for latest AI news" };

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Tools = tools,
      Messages = [userMessage]
  });

  if (response.StopReason == "pause_turn")
  {
      // Continue a conversa enviando a resposta de volta
      var continuation = await client.Messages.Create(new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 4096,
          Tools = tools,
          Messages =
          [
              userMessage,
              new AssistantMessageParam
              {
                  Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
              }
          ]
      });
  }
  ```

  ```go Go
  tools := []anthropic.ToolUnionParam{
  	{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{}},
  }
  userMessage := anthropic.NewUserMessage(anthropic.NewTextBlock("Search for latest AI news"))

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Tools:     tools,
  	Messages:  []anthropic.MessageParam{userMessage},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == "pause_turn" {
  	// Continue a conversa enviando a resposta de volta
  	var contentParams []anthropic.ContentBlockParamUnion
  	for _, block := range response.Content {
  		contentParams = append(contentParams, block.ToParam())
  	}
  	continuation, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 4096,
  		Tools:     tools,
  		Messages:  []anthropic.MessageParam{userMessage, anthropic.NewAssistantMessage(contentParams...)},
  	})
  	if err != nil {
  		log.Fatal(err)
  	}
  	_ = continuation
  }
  ```

  ```java Java
  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addTool(WebSearchTool20250305.builder().build())
          .addUserMessage("Search for latest AI news")
          .build()
  );

  if (response.stopReason().map(StopReason.PAUSE_TURN::equals).orElse(false)) {
      // Continue a conversa enviando a resposta de volta
      Message continuation = client.messages().create(
          MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(4096L)
              .addTool(WebSearchTool20250305.builder().build())
              .addUserMessage("Search for latest AI news")
              .addMessage(response)
              .build()
      );
  }
  ```

  ```php PHP
  $tools = [['type' => 'web_search_20250305', 'name' => 'web_search']];
  $userMessage = ['role' => 'user', 'content' => 'Search for latest AI news'];

  $response = $client->messages->create(
      maxTokens: 4096,
      messages: [$userMessage],
      model: 'claude-opus-5-5',
      tools: $tools,
  );

  if ($response->stopReason === 'pause_turn') {
      // Continue a conversa enviando a resposta de volta
      $continuation = $client->messages->create(
          maxTokens: 4096,
          messages: [
              $userMessage,
              ['role' => 'assistant', 'content' => $response->content],
          ],
          model: 'claude-opus-5-5',
          tools: $tools,
      );
  }
  ```

  ```ruby Ruby
  tools = [{ type: "web_search_20250305", name: "web_search" }]
  user_message = { role: "user", content: "Search for latest AI news" }

  response = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 4096,
    tools: tools,
    messages: [user_message]
  )

  if response.stop_reason == :pause_turn
    # Continue a conversa enviando a resposta de volta
    continuation = client.messages.create(
      model: "claude-opus-5-5",
      max_tokens: 4096,
      tools: tools,
      messages: [user_message, { role: "assistant", content: response.content }]
    )
  end
  ```
</CodeGroup>

Sua aplicação deve lidar com `pause_turn` em qualquer loop de agente que use ferramentas de servidor. Para um loop que lida com pausas repetidas e envia o ID do contêiner de volta, consulte [Implemente lógica de nova tentativa para pause\_turn](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#implement-retry-logic-for-pause-turn).

### refusal

Claude se recusou a gerar uma resposta. Os classificadores de segurança retornam esse motivo de parada como uma resposta HTTP 200 normal, não como um erro.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "[Unsafe request]"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "[Unsafe request]"}'
  ```

  ```python Python
  client = anthropic.Anthropic()
  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "[Unsafe request]"}],
  )

  if response.stop_reason == "refusal":
      # Claude se recusou a responder
      print("Claude was unable to process this request")
      # Considere reformular ou modificar a solicitação
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "[Unsafe request]" }]
  });

  if (response.stop_reason === "refusal") {
    // Claude se recusou a responder
    console.log("Claude was unable to process this request");
    // Considere reformular ou modificar a solicitação
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var response = await client.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Messages = [new UserMessageParam { Content = "[Unsafe request]" }]
  });

  if (response.StopReason == "refusal")
  {
      // Claude se recusou a responder
      Console.WriteLine("Claude was unable to process this request");
      // Considere reformular ou modificar a solicitação
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("[Unsafe request]")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == "refusal" {
  	// Claude se recusou a responder
  	fmt.Println("Claude was unable to process this request")
  	// Considere reformular ou modificar a solicitação
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(1024L)
          .addUserMessage("[Unsafe request]")
          .build()
  );

  if (response.stopReason().map(StopReason.REFUSAL::equals).orElse(false)) {
      // Claude se recusou a responder
      IO.println("Claude was unable to process this request");
      // Considere reformular ou modificar a solicitação
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => '[Unsafe request]']],
      model: Model::CLAUDE_OPUS_5_5,
  );

  if ($response->stopReason === 'refusal') {
      // Claude se recusou a responder
      echo 'Claude was unable to process this request', PHP_EOL;
      // Considere reformular ou modificar a solicitação
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "[Unsafe request]" }]
  )

  if response.stop_reason == :refusal
    # Claude se recusou a responder
    puts "Claude was unable to process this request"
    # Considere reformular ou modificar a solicitação
  end
  ```
</CodeGroup>

<Tip>
  Se você encontrar motivos de parada `refusal` com frequência ao usar o Claude Sonnet 4.5 ([descontinuado](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) ou o Claude Opus 4.1 (este último [desativado, exceto no Claude Models on Google Cloud (Google managed) e no Amazon Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)), você pode tentar atualizar suas chamadas de API para usar o Claude Haiku 4.5 (`claude-haiku-4-5-20251001`), que tem restrições de uso diferentes. Saiba mais sobre [como entender os filtros de segurança da API do Sonnet 4.5](https://support.claude.com/en/articles/12449294-understanding-sonnet-4-5-s-api-safety-filters).
</Tip>

Em uma recusa, o objeto [`stop_details`](https://platform.claude.com/docs/pt-BR/api/messages/create#message.stop_details) identifica a categoria de política que a acionou. As categorias e o formato completo da resposta de recusa são abordados em [Como é uma recusa](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#refusal-response). `stop_details` é `null` para todos os motivos de parada diferentes de `refusal`.

Geralmente você pode obter uma resposta para uma requisição recusada tentando novamente em outro modelo Claude. Isso funciona para o Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Haiku 5.5. [Recusas e fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback) mostra como configurar essa nova tentativa, no lado do servidor ou no seu cliente. O Claude Haiku 5.5 não tem fallback no lado do servidor, então configure a nova tentativa dele com [fallback no lado do cliente](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#client-side-fallback). Se você mesmo criar a nova tentativa a partir de qualquer um desses modelos, exceto o Claude Haiku 5.5, o [Crédito de fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/fallback-credit) explica como evitar pagar duas vezes o custo do cache de prompt.

### model\_context\_window\_exceeded

Claude parou porque atingiu o limite da “context window” (janela de contexto) do modelo. Isso permite que você solicite o máximo possível de tokens sem saber o tamanho exato da entrada.

<Note>
  Este motivo de parada atualmente é tipado apenas no namespace `beta` (csharp, go: `Beta`; java: `beta()`) do SDK, então os exemplos a seguir chamam `client.beta.messages` (csharp, go: `client.Beta.Messages`; java: `client.beta().messages()`; php: `$client->beta->messages`) e usam os tipos com prefixo `Beta`. No Sonnet 4.5 (descontinuado) e em modelos mais recentes, a API retorna esse valor sem um cabeçalho beta. Para modelos anteriores, adicione o cabeçalho beta `model-context-window-exceeded-2025-08-26` para habilitá-lo.
</Note>

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 20000,
      "messages": [{"role": "user", "content": "Large input that uses most of context window..."}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 20000 \
    --message '{role: user, content: "Large input that uses most of context window..."}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Requisição com o máximo de tokens para obter o máximo possível
  response = client.beta.messages.create(
      model="claude-opus-5-5",
      max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
      messages=[
          {"role": "user", "content": "Large input that uses most of context window..."}
      ],
  )

  if response.stop_reason == "model_context_window_exceeded":
      # A resposta atingiu o limite da janela de contexto antes de max_tokens
      print("Response reached model's context window limit")
      # A resposta ainda é válida, mas foi limitada pela janela de contexto
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Requisição com o máximo de tokens para obter o máximo possível
  const response = await client.beta.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 20000,
    messages: [{ role: "user", content: "Large input that uses most of context window..." }]
  });

  if (response.stop_reason === "model_context_window_exceeded") {
    // A resposta atingiu o limite da janela de contexto antes de max_tokens
    console.log("Response reached model's context window limit");
    // A resposta ainda é válida, mas foi limitada pela janela de contexto
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Requisição com o máximo de tokens para obter o máximo possível
  var response = await client.Beta.Messages.Create(new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 20000,
      Messages = [new BetaUserMessageParam { Content = "Large input that uses most of context window..." }]
  });

  if (response.StopReason?.Value() == BetaStopReason.ModelContextWindowExceeded)
  {
      // A resposta atingiu o limite da janela de contexto antes de max_tokens
      Console.WriteLine("Response reached model's context window limit");
      // A resposta ainda é válida, mas foi limitada pela janela de contexto
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  // Requisição com o máximo de tokens para obter o máximo possível
  response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 20000,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Large input that uses most of context window...")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  if response.StopReason == anthropic.BetaStopReasonModelContextWindowExceeded {
  	// A resposta atingiu o limite da janela de contexto antes de max_tokens
  	fmt.Println("Response reached model's context window limit")
  	// A resposta ainda é válida, mas foi limitada pela janela de contexto
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Requisição com o máximo de tokens para obter o máximo possível
  BetaMessage response = client.beta().messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(20000L)
          .addUserMessage("Large input that uses most of context window...")
          .build()
  );

  if (response.stopReason().map(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED::equals).orElse(false)) {
      // A resposta atingiu o limite da janela de contexto antes de max_tokens
      IO.println("Response reached model's context window limit");
      // A resposta ainda é válida, mas foi limitada pela janela de contexto
  }
  ```

  ```php PHP
  $client = new Client();

  // Requisição com o máximo de tokens para obter o máximo possível
  $response = $client->beta->messages->create(
      maxTokens: 20000,
      messages: [['role' => 'user', 'content' => 'Large input that uses most of context window...']],
      model: 'claude-opus-5-5',
  );

  if ($response->stopReason === 'model_context_window_exceeded') {
      // A resposta atingiu o limite da janela de contexto antes de max_tokens
      echo 'Response reached model\'s context window limit', PHP_EOL;
      // A resposta ainda é válida, mas foi limitada pela janela de contexto
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Requisição com o máximo de tokens para obter o máximo possível
  response = client.beta.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 20000,
    messages: [{ role: "user", content: "Large input that uses most of context window..." }]
  )

  if response.stop_reason == :model_context_window_exceeded
    # A resposta atingiu o limite da janela de contexto antes de max_tokens
    puts "Response reached model's context window limit"
    # A resposta ainda é válida, mas foi limitada pela janela de contexto
  end
  ```
</CodeGroup>

## Melhores práticas para lidar com motivos de parada

### Sempre verifique o stop\_reason

Crie o hábito de verificar o `stop_reason` na sua lógica de tratamento de respostas:

<CodeGroup exclude="shell">
  ```python Python
  def handle_response(response):
      match response.stop_reason:
          case "tool_use":
              return handle_tool_use(response)
          case "max_tokens":
              return handle_truncation(response)
          case "model_context_window_exceeded":
              return handle_context_limit(response)
          case "pause_turn":
              return handle_pause(response)
          case "refusal":
              return handle_refusal(response)
          case _:
              # Trata end_turn e outros casos
              return next(
                  (block.text for block in response.content if block.type == "text"),
                  "",
              )
  ```

  ```typescript TypeScript
  function handleResponse(response: Anthropic.Beta.BetaMessage): string {
    switch (response.stop_reason) {
      case "tool_use":
        return handleToolUse(response);
      case "max_tokens":
        return handleTruncation(response);
      case "model_context_window_exceeded":
        return handleContextLimit(response);
      case "pause_turn":
        return handlePause(response);
      case "refusal":
        return handleRefusal(response);
      default: {
        // Trata end_turn e outros casos
        const textBlock = response.content.find((block) => block.type === "text");
        return textBlock?.text ?? "";
      }
    }
  }
  ```

  ```csharp C#
  static string HandleResponse(BetaMessage response)
  {
      return response.StopReason?.Value() switch
      {
          BetaStopReason.ToolUse => HandleToolUse(response),
          BetaStopReason.MaxTokens => HandleTruncation(response),
          BetaStopReason.ModelContextWindowExceeded => HandleContextLimit(response),
          BetaStopReason.PauseTurn => HandlePause(response),
          BetaStopReason.Refusal => HandleRefusal(response),
          // Trata end_turn e outros casos
          _ => response.Content.Select(b => b.Value).OfType<BetaTextBlock>().FirstOrDefault()?.Text ?? "",
      };
  }
  ```

  ```go Go
  func handleResponse(response *anthropic.BetaMessage) string {
  	switch response.StopReason {
  	case anthropic.BetaStopReasonToolUse:
  		return handleToolUse(response)
  	case anthropic.BetaStopReasonMaxTokens:
  		return handleTruncation(response)
  	case anthropic.BetaStopReasonModelContextWindowExceeded:
  		return handleContextLimit(response)
  	case anthropic.BetaStopReasonPauseTurn:
  		return handlePause(response)
  	case anthropic.BetaStopReasonRefusal:
  		return handleRefusal(response)
  	default:
  		// Tratar end_turn e outros casos
  		for _, block := range response.Content {
  			if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  				return textBlock.Text
  			}
  		}
  		return ""
  	}
  }
  ```

  ```java Java
  static String handleResponse(BetaMessage response) {
      BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
      if (reason.equals(BetaStopReason.TOOL_USE)) {
          return handleToolUse(response);
      } else if (reason.equals(BetaStopReason.MAX_TOKENS)) {
          return handleTruncation(response);
      } else if (reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
          return handleContextLimit(response);
      } else if (reason.equals(BetaStopReason.PAUSE_TURN)) {
          return handlePause(response);
      } else if (reason.equals(BetaStopReason.REFUSAL)) {
          return handleRefusal(response);
      }
      // Trata end_turn e outros casos
      return response.content().stream()
          .filter(BetaContentBlock::isText)
          .findFirst()
          .map(block -> block.asText().text())
          .orElse("");
  }
  ```

  ```php PHP
  function handle_response($response): string
  {
      return match ($response->stopReason) {
          'tool_use' => handle_tool_use($response),
          'max_tokens' => handle_truncation($response),
          'model_context_window_exceeded' => handle_context_limit($response),
          'pause_turn' => handle_pause($response),
          'refusal' => handle_refusal($response),
          // Tratar end_turn e outros casos
          default => array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '',
      };
  }
  ```

  ```ruby Ruby
  def handle_response(response)
    case response.stop_reason
    when :tool_use then handle_tool_use(response)
    when :max_tokens then handle_truncation(response)
    when :model_context_window_exceeded then handle_context_limit(response)
    when :pause_turn then handle_pause(response)
    when :refusal then handle_refusal(response)
    else
      # Trata end_turn e outros casos
      response.content.find { it.type == :text }&.text
    end
  end
  ```
</CodeGroup>

### Lide com respostas truncadas de forma elegante

Quando uma resposta é truncada por causa de limites de tokens ou da janela de contexto, acrescente um aviso para que o leitor saiba que a saída está incompleta. Para, em vez disso, continuar gerando a partir de onde a resposta parou, consulte [Garantindo respostas completas](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#ensuring-complete-responses).

<CodeGroup exclude="shell">
  ```python Python
  def handle_truncated_response(response):
      text = next((block.text for block in response.content if block.type == "text"), "")
      if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
          if response.stop_reason == "max_tokens":
              note = "[Response truncated due to max_tokens limit]"
          else:
              note = "[Response truncated due to context window limit]"
          return f"{text}\n\n{note}"
      return text
  ```

  ```typescript TypeScript
  function handleTruncatedResponse(response: Anthropic.Beta.BetaMessage): string {
    const textBlock = response.content.find((block) => block.type === "text");
    const text = textBlock?.text ?? "";

    if (
      response.stop_reason === "max_tokens" ||
      response.stop_reason === "model_context_window_exceeded"
    ) {
      const note =
        response.stop_reason === "max_tokens"
          ? "[Response truncated due to max_tokens limit]"
          : "[Response truncated due to context window limit]";
      return `${text}\n\n${note}`;
    }
    return text;
  }
  ```

  ```csharp C#
  static string HandleTruncatedResponse(BetaMessage response)
  {
      var text = response.Content.Select(b => b.Value).OfType<BetaTextBlock>().FirstOrDefault()?.Text ?? "";
      var reason = response.StopReason?.Value();

      if (reason is BetaStopReason.MaxTokens or BetaStopReason.ModelContextWindowExceeded)
      {
          var note = reason == BetaStopReason.MaxTokens
              ? "[Response truncated due to max_tokens limit]"
              : "[Response truncated due to context window limit]";
          return $"{text}\n\n{note}";
      }
      return text;
  }
  ```

  ```go Go
  func handleTruncatedResponse(response *anthropic.BetaMessage) string {
  	text := ""
  	for _, block := range response.Content {
  		if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  			text = textBlock.Text
  			break
  		}
  	}

  	if response.StopReason == anthropic.BetaStopReasonMaxTokens ||
  		response.StopReason == anthropic.BetaStopReasonModelContextWindowExceeded {
  		note := "[Response truncated due to context window limit]"
  		if response.StopReason == anthropic.BetaStopReasonMaxTokens {
  			note = "[Response truncated due to max_tokens limit]"
  		}
  		return text + "\n\n" + note
  	}
  	return text
  }
  ```

  ```java Java
  static String handleTruncatedResponse(BetaMessage response) {
      String text = response.content().stream()
          .filter(BetaContentBlock::isText)
          .findFirst()
          .map(block -> block.asText().text())
          .orElse("");
      BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);

      if (reason.equals(BetaStopReason.MAX_TOKENS)
              || reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
          String note = reason.equals(BetaStopReason.MAX_TOKENS)
              ? "[Response truncated due to max_tokens limit]"
              : "[Response truncated due to context window limit]";
          return text + "\n\n" + note;
      }
      return text;
  }
  ```

  ```php PHP
  function handle_truncated_response($response): string
  {
      $text = array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';

      if (in_array($response->stopReason, ['max_tokens', 'model_context_window_exceeded'], true)) {
          $note = $response->stopReason === 'max_tokens'
              ? '[Response truncated due to max_tokens limit]'
              : '[Response truncated due to context window limit]';
          return "{$text}\n\n{$note}";
      }
      return $text;
  }
  ```

  ```ruby Ruby
  def handle_truncated_response(response)
    text = response.content.find { it.type == :text }&.text

    if [:max_tokens, :model_context_window_exceeded].include?(response.stop_reason)
      note = if response.stop_reason == :max_tokens
        "[Response truncated due to max_tokens limit]"
      else
        "[Response truncated due to context window limit]"
      end
      return "#{text}\n\n#{note}"
    end
    text
  end
  ```
</CodeGroup>

### Implemente lógica de nova tentativa para pause\_turn

Quando você usa [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools), a API pode retornar `pause_turn` se o loop de amostragem do lado do servidor atingir seu limite de iterações (padrão 10). Lide com isso adicionando a resposta pausada às suas mensagens sem alterações e enviando a solicitação novamente. Se a resposta incluir um `container`, [envie o ID dele de volta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#container-reuse) também. Sem ele, a próxima solicitação inicia um novo contêiner, e os arquivos de etapas anteriores do turno são perdidos.

<CodeGroup exclude="shell:cURL, shell:CLI">
  <CodeGroupItem language="cURL">
    Este fluxo de trabalho precisa de mais lógica do que um único comando de shell. Use o [Anthropic SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) para executá-lo.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Este fluxo de trabalho precisa de mais lógica do que um único comando de shell. Use o [Anthropic SDK](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/overview) para executá-lo.
  </CodeGroupItem>

  ```python Python
  client = anthropic.Anthropic()


  def handle_server_tool_conversation(client, user_query, tools, max_requests=5):
      messages = [{"role": "user", "content": user_query}]
      container_id = None

      for _ in range(max_requests):
          response = client.messages.create(
              model="claude-opus-5-5",
              max_tokens=4096,
              messages=messages,
              tools=tools,
              container=container_id,
          )

          if response.stop_reason != "pause_turn":
              # Não pausado: retorna a resposta
              return response

          # pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
          messages.append({"role": "assistant", "content": response.content})

          # Se as ferramentas rodaram em um contêiner, envie o ID dele de volta para manter seus arquivos
          if response.container:
              container_id = response.container.id

      # Ainda pausado após max_requests requisições: retorna a última resposta
      return response


  response = handle_server_tool_conversation(
      client,
      "Use the code execution tool to find the 1,000th prime number.",
      [{"type": "code_execution_20250825", "name": "code_execution"}],
  )
  print(response.stop_reason)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  async function handleServerToolConversation(
    client: Anthropic,
    userQuery: string,
    tools: Anthropic.ToolUnion[],
    maxRequests = 5
  ): Promise<Anthropic.Message> {
    const messages: Anthropic.MessageParam[] = [{ role: "user", content: userQuery }];
    let containerId: string | null = null;
    let response: Anthropic.Message;
    let requestCount = 0;

    do {
      response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 4096,
        messages,
        tools,
        container: containerId
      });

      if (response.stop_reason !== "pause_turn") {
        // Não pausado: retorna a resposta
        return response;
      }

      // pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
      messages.push({ role: "assistant", content: response.content });

      // Se as ferramentas rodaram em um contêiner, envia o ID dele de volta para manter seus arquivos
      if (response.container) {
        containerId = response.container.id;
      }
    } while (++requestCount < maxRequests);

    // Ainda pausado após maxRequests requisições: retorna a última resposta
    return response;
  }

  const response = await handleServerToolConversation(
    client,
    "Use the code execution tool to find the 1,000th prime number.",
    [{ type: "code_execution_20250825", name: "code_execution" }]
  );
  console.log(response.stop_reason);
  ```

  ```csharp C#
  // Um turno de ferramenta de servidor pode durar minutos, mais que o timeout padrão do SDK,
  // que ele define a partir de MaxTokens (cerca de 2 minutos com 4096).
  AnthropicClient client = new() { Timeout = TimeSpan.FromMinutes(10) };

  static async Task<Message> HandleServerToolConversation(
      AnthropicClient client,
      string userQuery,
      List<ToolUnion> tools,
      int maxRequests = 5)
  {
      List<MessageParam> messages = [new UserMessageParam { Content = userQuery }];
      MessageCreateParamsContainer? container = null;
      Message response;
      var requestCount = 0;

      do
      {
          response = await client.Messages.Create(new MessageCreateParams
          {
              Model = Model.ClaudeOpus5_5,
              MaxTokens = 4096,
              Messages = messages,
              Tools = tools,
              Container = container
          });

          if (response.StopReason != StopReason.PauseTurn)
          {
              // Não pausado: retorna a resposta
              return response;
          }

          // pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
          // Blocos de requisição e de resposta são tipos distintos: copie o JSON de cada bloco sem alterações
          messages.Add(new AssistantMessageParam
          {
              Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
          });

          // Se as ferramentas rodaram em um contêiner, envie o ID dele de volta para manter seus arquivos
          if (response.Container is not null)
          {
              container = response.Container.ID;
          }
      } while (++requestCount < maxRequests);

      // Ainda pausado após maxRequests requisições: retorna a última resposta
      return response;
  }

  var response = await HandleServerToolConversation(
      client,
      "Use the code execution tool to find the 1,000th prime number.",
      [new CodeExecutionTool20250825()]);
  Console.WriteLine(response.StopReason?.Raw());
  ```

  ```go Go
  func handleServerToolConversation(
  	client anthropic.Client,
  	userQuery string,
  	tools []anthropic.ToolUnionParam,
  	maxRequests int,
  ) (*anthropic.Message, error) {
  	messages := []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery)),
  	}
  	var container anthropic.MessageCreateParamsContainerUnion
  	var response *anthropic.Message
  	var err error

  	for range maxRequests {
  		response, err = client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  			Model:     anthropic.ModelClaudeOpus5_5,
  			MaxTokens: 4096,
  			Messages:  messages,
  			Tools:     tools,
  			Container: container,
  		})
  		if err != nil {
  			return nil, err
  		}

  		if response.StopReason != anthropic.StopReasonPauseTurn {
  			// Não pausado: retorna a resposta
  			return response, nil
  		}

  		// pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
  		messages = append(messages, response.ToParam())

  		// Se as ferramentas rodaram em um contêiner, envie o ID dele de volta para manter seus arquivos
  		if response.Container.ID != "" {
  			container.OfString = anthropic.String(response.Container.ID)
  		}
  	}

  	// Ainda pausado após maxRequests requisições: retorna a última resposta
  	return response, nil
  }

  func main() {
  	client := anthropic.NewClient()

  	response, err := handleServerToolConversation(
  		client,
  		"Use the code execution tool to find the 1,000th prime number.",
  		[]anthropic.ToolUnionParam{
  			{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  		},
  		5,
  	)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.StopReason)
  }
  ```

  ```java Java
  Message handleServerToolConversation(
      AnthropicClient client,
      String userQuery,
      List<ToolUnion> tools,
      int maxRequests
  ) {
      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .tools(tools)
          .addUserMessage(userQuery);
      Message response = null;

      for (int request = 0; request < maxRequests; request++) {
          response = client.messages().create(params.build());

          boolean paused = response.stopReason().filter(StopReason.PAUSE_TURN::equals).isPresent();
          if (!paused) {
              // Não pausado: retorna a resposta
              return response;
          }

          // pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
          params.addMessage(response);

          // Se as ferramentas rodaram em um contêiner, envia o ID dele de volta para manter seus arquivos
          response.container().ifPresent(container -> params.container(container.id()));
      }

      // Ainda pausado após maxRequests requisições: retorna a última resposta
      return response;
  }

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      Message response = handleServerToolConversation(
          client,
          "Use the code execution tool to find the 1,000th prime number.",
          List.of(ToolUnion.ofCodeExecutionTool20250825(CodeExecutionTool20250825.builder().build())),
          5
      );
      response.stopReason().ifPresent(IO::println);
  }
  ```

  ```php PHP
  $client = new Client();

  function handle_server_tool_conversation(
      Client $client,
      string $userQuery,
      array $tools,
      int $maxRequests = 5,
  ): Message {
      $messages = [['role' => 'user', 'content' => $userQuery]];
      $containerId = null;
      $requestCount = 0;

      do {
          $response = $client->messages->create(
              maxTokens: 4096,
              messages: $messages,
              model: Model::CLAUDE_OPUS_5_5,
              tools: $tools,
              container: $containerId,
          );

          if ($response->stopReason !== StopReason::PAUSE_TURN->value) {
              // Não pausado: retorna a resposta
              return $response;
          }

          // pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
          $messages[] = ['role' => 'assistant', 'content' => $response->content];

          // Se as ferramentas rodaram em um contêiner, envia o ID dele de volta para manter seus arquivos
          $containerId = $response->container->id ?? $containerId;
      } while (++$requestCount < $maxRequests);

      // Ainda pausado após $maxRequests requisições: retorna a última resposta
      return $response;
  }

  $response = handle_server_tool_conversation(
      $client,
      'Use the code execution tool to find the 1,000th prime number.',
      [new CodeExecutionTool20250825()],
  );
  echo $response->stopReason, PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  def handle_server_tool_conversation(client, user_query, tools, max_requests: 5)
    messages = [{ role: "user", content: user_query }]
    container_id = nil
    response = nil

    max_requests.times do
      response = client.messages.create(
        model: Anthropic::Model::CLAUDE_OPUS_5_5,
        max_tokens: 4096,
        messages:,
        tools:,
        container: container_id
      )

      # Não pausado: retorna a resposta
      return response unless response.stop_reason == :pause_turn

      # pause_turn: adiciona a resposta pausada como mensagem do assistente e continua
      messages << { role: "assistant", content: response.content }

      # Se as ferramentas rodaram em um contêiner, envie o ID dele de volta para manter seus arquivos
      container_id = response.container&.id || container_id
    end

    # Ainda pausado após max_requests requisições: retorna a última resposta
    response
  end

  response = handle_server_tool_conversation(
    client,
    "Use the code execution tool to find the 1,000th prime number.",
    [Anthropic::CodeExecutionTool20250825.new]
  )
  puts response.stop_reason
  ```
</CodeGroup>

A função retorna a última resposta, que contém apenas a parte final do turno. Para exibir o turno inteiro ou para continuar a conversa, mantenha também as respostas pausadas.

## Motivos de parada versus erros

É importante distinguir entre valores de `stop_reason` e erros reais:

### Motivos de parada (respostas bem-sucedidas)

* Fazem parte do corpo da resposta
* Indicam por que a geração parou normalmente
* A resposta contém conteúdo válido

### Erros (requisições com falha)

* Códigos de status HTTP 4xx ou 5xx
* Indicam falhas no processamento da requisição
* A resposta contém detalhes do erro

<CodeGroup>
  ```bash cURL
  # O cURL sai com código diferente de zero em erros HTTP com --fail-with-body; verifique
  # $? para erros e stop_reason para respostas bem-sucedidas.
  curl --fail-with-body https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```bash CLI
  # A CLI sai com código diferente de zero em erros da API; stop_reason aparece em caso de sucesso.
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello!"}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  try:
      response = client.messages.create(
          model="claude-opus-5-5",
          max_tokens=1024,
          messages=[{"role": "user", "content": "Hello!"}],
      )

      # Trata a resposta bem-sucedida com stop_reason
      if response.stop_reason == "max_tokens":
          print("Response was truncated")

  except anthropic.APIStatusError as e:
      # Trata os erros reais
      match e.status_code:
          case 429:
              print("Rate limit exceeded")
          case 500:
              print("Server error")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  try {
    const response = await client.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 1024,
      messages: [{ role: "user", content: "Hello!" }]
    });

    // Trata a resposta bem-sucedida com stop_reason
    if (response.stop_reason === "max_tokens") {
      console.log("Response was truncated");
    }
  } catch (err) {
    // Trata os erros reais
    if (err instanceof Anthropic.APIError) {
      switch (err.status) {
        case 429:
          console.log("Rate limit exceeded");
          break;
        case 500:
          console.log("Server error");
          break;
      }
    } else {
      throw err;
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  try
  {
      var response = await client.Messages.Create(new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages = [new UserMessageParam { Content = "Hello!" }]
      });

      // Trata a resposta bem-sucedida com stop_reason
      if (response.StopReason == "max_tokens")
      {
          Console.WriteLine("Response was truncated");
      }
  }
  catch (AnthropicRateLimitException)
  {
      // Trata os erros reais
      Console.WriteLine("Rate limit exceeded");
  }
  catch (Anthropic5xxException)
  {
      Console.WriteLine("Server error");
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
  	},
  })
  if err != nil {
  	// Trata erros reais
  	var apiErr *anthropic.Error
  	if errors.As(err, &apiErr) {
  		switch apiErr.StatusCode {
  		case 429:
  			fmt.Println("Rate limit exceeded")
  		case 500:
  			fmt.Println("Server error")
  		}
  	}
  	log.Fatal(err)
  }

  // Trata resposta bem-sucedida com stop_reason
  if response.StopReason == "max_tokens" {
  	fmt.Println("Response was truncated")
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  try {
      Message response = client.messages().create(
          MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024L)
              .addUserMessage("Hello!")
              .build()
      );

      // Trata a resposta bem-sucedida com stop_reason
      if (response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
          IO.println("Response was truncated");
      }
  } catch (RateLimitException e) {
      // Trata os erros reais
      IO.println("Rate limit exceeded");
  } catch (AnthropicServiceException e) {
      if (e.statusCode() == 500) {
          IO.println("Server error");
      }
  }
  ```

  ```php PHP
  $client = new Client();

  try {
      $response = $client->messages->create(
          maxTokens: 1024,
          messages: [['role' => 'user', 'content' => 'Hello!']],
          model: Model::CLAUDE_OPUS_5_5,
      );

      // Trata a resposta bem-sucedida com stop_reason
      if ($response->stopReason === 'max_tokens') {
          echo 'Response was truncated', PHP_EOL;
      }
  } catch (RateLimitException $e) {
      // Trata os erros reais
      echo 'Rate limit exceeded', PHP_EOL;
  } catch (InternalServerException $e) {
      echo 'Server error', PHP_EOL;
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  begin
    response = client.messages.create(
      model: Anthropic::Model::CLAUDE_OPUS_5_5,
      max_tokens: 1024,
      messages: [{ role: "user", content: "Hello!" }]
    )

    # Trata a resposta bem-sucedida com stop_reason
    if response.stop_reason == :max_tokens
      puts "Response was truncated"
    end
  rescue Anthropic::Errors::RateLimitError
    # Trata os erros reais
    puts "Rate limit exceeded"
  rescue Anthropic::Errors::APIStatusError => e
    puts "Server error" if e.status == 500
  end
  ```
</CodeGroup>

## Considerações sobre streaming

Ao usar streaming, o `stop_reason` é:

* `null` no evento inicial `message_start`
* Fornecido no evento `message_delta`
* Não fornecido em nenhum outro evento

<CodeGroup>
  ```bash cURL
  # O evento message_delta no stream SSE contém o stop_reason.
  curl -N https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "stream": true,
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```

  ```bash CLI
  # stop_reason aparece no evento message_delta.
  ant messages create --stream \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello!"}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  with client.messages.stream(
      model="claude-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello!"}],
  ) as stream:
      for event in stream:
          if event.type == "message_delta":
              stop_reason = event.delta.stop_reason
              if stop_reason:
                  print(f"Stream ended with: {stop_reason}")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const stream = client.messages.stream({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }]
  });

  for await (const event of stream) {
    if (event.type === "message_delta" && event.delta.stop_reason) {
      console.log(`Stream ended with: ${event.delta.stop_reason}`);
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Messages = [new UserMessageParam { Content = "Hello!" }]
  };

  await foreach (var streamEvent in client.Messages.CreateStreaming(parameters))
  {
      switch (streamEvent.Value)
      {
          case RawMessageDeltaEvent deltaEvent when deltaEvent.Delta.StopReason is not null:
              Console.WriteLine($"Stream ended with: {deltaEvent.Delta.StopReason}");
              break;
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
  	},
  })

  // Acumula os eventos na Message final, que contém o stop_reason.
  message := anthropic.Message{}
  for stream.Next() {
  	if err := message.Accumulate(stream.Current()); err != nil {
  		log.Fatal(err)
  	}
  }
  if err := stream.Err(); err != nil {
  	log.Fatal(err)
  }

  if message.StopReason != "" {
  	fmt.Printf("Stream ended with: %s\n", message.StopReason)
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024L)
      .addUserMessage("Hello!")
      .build();

  // Acumula os eventos na Message final, que contém o stop_reason.
  MessageAccumulator accumulator = MessageAccumulator.create();
  try (StreamResponse<RawMessageStreamEvent> streamResponse =
          client.messages().createStreaming(params)) {
      streamResponse.stream().forEach(accumulator::accumulate);
  }

  accumulator.message().stopReason().ifPresent(stopReason ->
      IO.println("Stream ended with: " + stopReason)
  );
  ```

  ```php PHP
  $client = new Client();

  $stream = $client->messages->createStream(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello!']],
      model: Model::CLAUDE_OPUS_5_5,
  );

  foreach ($stream as $event) {
      if ($event instanceof \Anthropic\Messages\RawMessageDeltaEvent && $event->delta->stopReason !== null) {
          echo "Stream ended with: {$event->delta->stopReason}", PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  stream = client.messages.stream(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello!" }]
  )

  stream.each do |event|
    next unless event.type == :message_delta
    stop_reason = event.delta.stop_reason
    puts "Stream ended with: #{stop_reason}" if stop_reason
  end
  ```
</CodeGroup>

## Padrões comuns

### Lidando com fluxos de trabalho de uso de ferramentas

<Tip>
  **Mais simples com o tool runner:** O exemplo a seguir mostra o tratamento manual de ferramentas. Para a maioria dos casos de uso, o [tool runner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner) lida automaticamente com a execução de ferramentas com muito menos código.
</Tip>

<CodeGroup exclude="shell">
  ```python Python
  def complete_tool_workflow(client, user_query, tools):
      messages = [{"role": "user", "content": user_query}]

      while True:
          response = client.messages.create(
              model="claude-opus-5-5",
              max_tokens=1024,
              messages=messages,
              tools=tools,
          )

          if response.stop_reason == "tool_use":
              # Executa as ferramentas e continua
              tool_results = execute_tools(response.content)
              messages.append({"role": "assistant", "content": response.content})
              messages.append({"role": "user", "content": tool_results})
          else:
              # Resposta final
              return response
  ```

  ```typescript TypeScript
  async function completeToolWorkflow(
    client: Anthropic,
    userQuery: string,
    tools: Anthropic.ToolUnion[]
  ): Promise<Anthropic.Message> {
    const messages: Anthropic.MessageParam[] = [{ role: "user", content: userQuery }];

    while (true) {
      const response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages,
        tools
      });

      if (response.stop_reason === "tool_use") {
        // Executar as ferramentas e continuar
        const toolResults = executeTools(response.content);
        messages.push({ role: "assistant", content: response.content });
        messages.push({ role: "user", content: toolResults });
      } else {
        // Resposta final
        return response;
      }
    }
  }
  ```

  ```csharp C#
  static async Task<Message> CompleteToolWorkflow(
      AnthropicClient client,
      string userQuery,
      List<ToolUnion> tools)
  {
      List<MessageParam> messages = [new UserMessageParam { Content = userQuery }];

      while (true)
      {
          var response = await client.Messages.Create(new MessageCreateParams
          {
              Model = Model.ClaudeOpus5_5,
              MaxTokens = 1024,
              Messages = messages,
              Tools = tools
          });

          if (response.StopReason == "tool_use")
          {
              // Executa as ferramentas e continua
              var toolResults = ExecuteTools(response.Content);
              messages.Add(new AssistantMessageParam
              {
                  Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
              });
              messages.Add(new UserMessageParam { Content = toolResults });
          }
          else
          {
              // Resposta final
              return response;
          }
      }
  }
  ```

  ```go Go
  func completeToolWorkflow(
  	client anthropic.Client,
  	userQuery string,
  	tools []anthropic.ToolUnionParam,
  ) (*anthropic.Message, error) {
  	messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(userQuery))}

  	for {
  		response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  			Model:     anthropic.ModelClaudeOpus5_5,
  			MaxTokens: 1024,
  			Messages:  messages,
  			Tools:     tools,
  		})
  		if err != nil {
  			return nil, err
  		}

  		if response.StopReason != "tool_use" {
  			// Resposta final
  			return response, nil
  		}

  		// Executa as ferramentas e continua
  		toolResults := executeTools(response.Content)
  		var contentParams []anthropic.ContentBlockParamUnion
  		for _, block := range response.Content {
  			contentParams = append(contentParams, block.ToParam())
  		}
  		messages = append(messages, anthropic.NewAssistantMessage(contentParams...))
  		messages = append(messages, anthropic.NewUserMessage(toolResults...))
  	}
  }
  ```

  ```java Java
  static Message completeToolWorkflow(
      AnthropicClient client,
      String userQuery,
      List<Tool> tools
  ) {
      List<MessageParam> messages = new ArrayList<>();
      messages.add(MessageParam.ofUser(userQuery));

      while (true) {
          MessageCreateParams.Builder params = MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(1024L)
              .messages(messages);
          tools.forEach(params::addTool);

          Message response = client.messages().create(params.build());

          if (!response.stopReason().map(StopReason.TOOL_USE::equals).orElse(false)) {
              // Resposta final
              return response;
          }

          // Executa as ferramentas e continua
          List<ToolResultBlockParam> toolResults = executeTools(response.content());
          messages.add(response.toParam());
          messages.add(MessageParam.ofUserOfContentBlockParams(
              toolResults.stream().map(ContentBlockParam::ofToolResult).toList()));
      }
  }
  ```

  ```php PHP
  function complete_tool_workflow(Client $client, string $userQuery, array $tools)
  {
      $messages = [['role' => 'user', 'content' => $userQuery]];

      while (true) {
          $response = $client->messages->create(
              maxTokens: 1024,
              messages: $messages,
              model: 'claude-opus-5-5',
              tools: $tools,
          );

          if ($response->stopReason !== 'tool_use') {
              // Resposta final
              return $response;
          }

          // Executar ferramentas e continuar
          $toolResults = execute_tools($response->content);
          $messages[] = ['role' => 'assistant', 'content' => $response->content];
          $messages[] = ['role' => 'user', 'content' => $toolResults];
      }
  }
  ```

  ```ruby Ruby
  def complete_tool_workflow(client, user_query, tools)
    messages = [{ role: "user", content: user_query }]

    loop do
      response = client.messages.create(
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: messages,
        tools: tools
      )

      # Resposta final
      return response unless response.stop_reason == :tool_use

      # Executar as ferramentas e continuar
      tool_results = execute_tools(response.content)
      messages << { role: "assistant", content: response.content }
      messages << { role: "user", content: tool_results }
    end
  end
  ```
</CodeGroup>

### Garantindo respostas completas

<CodeGroup exclude="shell">
  ```python Python
  def get_complete_response(client, prompt, max_attempts=3):
      messages = [{"role": "user", "content": prompt}]
      full_response = ""

      for _ in range(max_attempts):
          response = client.messages.create(
              model="claude-opus-5-5", messages=messages, max_tokens=4096
          )

          full_response += next(
              (block.text for block in response.content if block.type == "text"), ""
          )

          if response.stop_reason != "max_tokens":
              break

          # Continua de onde parou
          messages = [
              {"role": "user", "content": prompt},
              {"role": "assistant", "content": full_response},
              {"role": "user", "content": "Please continue from where you left off."},
          ]

      return full_response
  ```

  ```typescript TypeScript
  async function getCompleteResponse(
    client: Anthropic,
    prompt: string,
    maxAttempts = 3
  ): Promise<string> {
    let messages: Anthropic.MessageParam[] = [{ role: "user", content: prompt }];
    let fullResponse = "";

    for (let i = 0; i < maxAttempts; i++) {
      const response = await client.messages.create({
        model: "claude-opus-5-5",
        max_tokens: 4096,
        messages
      });

      const textBlock = response.content.find((block) => block.type === "text");
      fullResponse += textBlock?.text ?? "";

      if (response.stop_reason !== "max_tokens") {
        break;
      }

      // Continua de onde parou
      messages = [
        { role: "user", content: prompt },
        { role: "assistant", content: fullResponse },
        { role: "user", content: "Please continue from where you left off." }
      ];
    }

    return fullResponse;
  }
  ```

  ```csharp C#
  static async Task<string> GetCompleteResponse(AnthropicClient client, string prompt, int maxAttempts = 3)
  {
      List<MessageParam> messages = [new UserMessageParam { Content = prompt }];
      var fullResponse = "";

      for (var i = 0; i < maxAttempts; i++)
      {
          var response = await client.Messages.Create(new MessageCreateParams
          {
              Model = Model.ClaudeOpus5_5,
              MaxTokens = 4096,
              Messages = messages
          });

          foreach (var block in response.Content)
          {
              if (block.TryPickText(out var textBlock))
              {
                  fullResponse += textBlock.Text;
                  break;
              }
          }

          if (response.StopReason != "max_tokens")
          {
              break;
          }

          // Continua de onde parou
          messages =
          [
              new UserMessageParam { Content = prompt },
              new AssistantMessageParam { Content = fullResponse },
              new UserMessageParam { Content = "Please continue from where you left off." }
          ];
      }

      return fullResponse;
  }
  ```

  ```go Go
  func getCompleteResponse(client anthropic.Client, prompt string, maxAttempts int) (string, error) {
  	messages := []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(prompt))}
  	fullResponse := ""

  	for range maxAttempts {
  		response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  			Model:     anthropic.ModelClaudeOpus5_5,
  			MaxTokens: 4096,
  			Messages:  messages,
  		})
  		if err != nil {
  			return "", err
  		}

  		for _, block := range response.Content {
  			if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  				fullResponse += textBlock.Text
  				break
  			}
  		}

  		if response.StopReason != "max_tokens" {
  			break
  		}

  		// Continua de onde parou
  		messages = []anthropic.MessageParam{
  			anthropic.NewUserMessage(anthropic.NewTextBlock(prompt)),
  			anthropic.NewAssistantMessage(anthropic.NewTextBlock(fullResponse)),
  			anthropic.NewUserMessage(anthropic.NewTextBlock("Please continue from where you left off.")),
  		}
  	}

  	return fullResponse, nil
  }
  ```

  ```java Java
  static String getCompleteResponse(AnthropicClient client, String prompt, int maxAttempts) {
      List<MessageParam> messages = List.of(MessageParam.ofUser(prompt));
      StringBuilder fullResponse = new StringBuilder();

      for (int i = 0; i < maxAttempts; i++) {
          Message response = client.messages().create(
              MessageCreateParams.builder()
                  .model(Model.CLAUDE_OPUS_5_5)
                  .maxTokens(4096L)
                  .messages(messages)
                  .build()
          );

          response.content().stream()
              .filter(ContentBlock::isText)
              .findFirst()
              .ifPresent(block -> fullResponse.append(block.asText().text()));

          if (!response.stopReason().map(StopReason.MAX_TOKENS::equals).orElse(false)) {
              break;
          }

          // Continua de onde parou
          messages = List.of(
              MessageParam.ofUser(prompt),
              MessageParam.ofAssistant(fullResponse.toString()),
              MessageParam.ofUser("Please continue from where you left off.")
          );
      }

      return fullResponse.toString();
  }
  ```

  ```php PHP
  function get_complete_response(Client $client, string $prompt, int $maxAttempts = 3): string
  {
      $messages = [['role' => 'user', 'content' => $prompt]];
      $fullResponse = '';

      for ($i = 0; $i < $maxAttempts; $i++) {
          $response = $client->messages->create(
              maxTokens: 4096,
              messages: $messages,
              model: 'claude-opus-5-5',
          );

          $fullResponse .= array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';

          if ($response->stopReason !== 'max_tokens') {
              break;
          }

          // Continua de onde parou
          $messages = [
              ['role' => 'user', 'content' => $prompt],
              ['role' => 'assistant', 'content' => $fullResponse],
              ['role' => 'user', 'content' => 'Please continue from where you left off.'],
          ];
      }

      return $fullResponse;
  }
  ```

  ```ruby Ruby
  def get_complete_response(client, prompt, max_attempts: 3)
    messages = [{ role: "user", content: prompt }]
    full_response = +""

    max_attempts.times do
      response = client.messages.create(
        model: "claude-opus-5-5",
        max_tokens: 4096,
        messages: messages
      )

      full_response << response.content.find { it.type == :text }&.text.to_s

      break unless response.stop_reason == :max_tokens

      # Continua de onde parou
      messages = [
        { role: "user", content: prompt },
        { role: "assistant", content: full_response },
        { role: "user", content: "Please continue from where you left off." }
      ]
    end

    full_response
  end
  ```
</CodeGroup>

### Obtendo o máximo de tokens sem saber o tamanho da entrada

Com o motivo de parada `model_context_window_exceeded`, você pode solicitar o máximo possível de tokens sem calcular o tamanho da entrada:

<CodeGroup exclude="shell">
  ```python Python
  def get_max_possible_tokens(client, prompt):
      """
      Get as many tokens as possible within the model's context window
      without needing to calculate input token count
      """
      response = client.beta.messages.create(
          model="claude-opus-5-5",
          messages=[{"role": "user", "content": prompt}],
          max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
      )

      match response.stop_reason:
          case "model_context_window_exceeded":
              # Obteve o máximo de tokens possível dado o tamanho da entrada
              print(
                  f"Generated {response.usage.output_tokens} tokens (context limit reached)"
              )
          case "max_tokens":
              # Obteve exatamente os tokens solicitados
              print(
                  f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
              )
          case _:
              # Conclusão natural
              print(
                  f"Generated {response.usage.output_tokens} tokens (natural completion)"
              )

      return next((block.text for block in response.content if block.type == "text"), "")
  ```

  ```typescript TypeScript
  async function getMaxPossibleTokens(client: Anthropic, prompt: string): Promise<string> {
    const response = await client.beta.messages.create({
      model: "claude-opus-5-5",
      max_tokens: 20000,
      messages: [{ role: "user", content: prompt }]
    });

    const tokens = response.usage.output_tokens;
    switch (response.stop_reason) {
      case "model_context_window_exceeded":
        // Obteve o máximo de tokens possível dado o tamanho da entrada
        console.log(`Generated ${tokens} tokens (context limit reached)`);
        break;
      case "max_tokens":
        // Obteve exatamente os tokens solicitados
        console.log(`Generated ${tokens} tokens (max_tokens reached)`);
        break;
      default:
        // Conclusão natural
        console.log(`Generated ${tokens} tokens (natural completion)`);
    }

    const textBlock = response.content.find((block) => block.type === "text");
    return textBlock?.text ?? "";
  }
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using Model = Anthropic.Models.Messages.Model;

  static async Task<string> GetMaxPossibleTokens(AnthropicClient client, string prompt)
  {
      var response = await client.Beta.Messages.Create(new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 20000,
          Messages = [new BetaUserMessageParam { Content = prompt }]
      });

      var tokens = response.Usage.OutputTokens;
      var reason = response.StopReason?.Value();
      if (reason == BetaStopReason.ModelContextWindowExceeded)
      {
          // Obteve o máximo de tokens possível dado o tamanho da entrada
          Console.WriteLine($"Generated {tokens} tokens (context limit reached)");
      }
      else if (reason == BetaStopReason.MaxTokens)
      {
          // Obteve exatamente os tokens solicitados
          Console.WriteLine($"Generated {tokens} tokens (max_tokens reached)");
      }
      else
      {
          // Conclusão natural
          Console.WriteLine($"Generated {tokens} tokens (natural completion)");
      }

      return response.Content.Select(b => b.Value).OfType<BetaTextBlock>().FirstOrDefault()?.Text ?? "";
  }
  ```

  ```go Go
  func getMaxPossibleTokens(client anthropic.Client, prompt string) (string, error) {
  	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 20000,
  		Messages: []anthropic.BetaMessageParam{
  			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)),
  		},
  	})
  	if err != nil {
  		return "", err
  	}

  	tokens := response.Usage.OutputTokens
  	switch response.StopReason {
  	case anthropic.BetaStopReasonModelContextWindowExceeded:
  		// Obteve o máximo de tokens possível dado o tamanho da entrada
  		fmt.Printf("Generated %d tokens (context limit reached)\n", tokens)
  	case anthropic.BetaStopReasonMaxTokens:
  		// Obteve exatamente os tokens solicitados
  		fmt.Printf("Generated %d tokens (max_tokens reached)\n", tokens)
  	default:
  		// Conclusão natural
  		fmt.Printf("Generated %d tokens (natural completion)\n", tokens)
  	}

  	for _, block := range response.Content {
  		if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
  			return textBlock.Text, nil
  		}
  	}
  	return "", nil
  }
  ```

  ```java Java
  import com.anthropic.models.beta.messages.BetaContentBlock;
  import com.anthropic.models.beta.messages.BetaMessage;
  import com.anthropic.models.beta.messages.BetaStopReason;
  import com.anthropic.models.beta.messages.MessageCreateParams;

  static String getMaxPossibleTokens(AnthropicClient client, String prompt) {
      BetaMessage response = client.beta().messages().create(
          MessageCreateParams.builder()
              .model(Model.CLAUDE_OPUS_5_5)
              .maxTokens(20000L)
              .addUserMessage(prompt)
              .build()
      );

      long tokens = response.usage().outputTokens();
      BetaStopReason reason = response.stopReason().orElse(BetaStopReason.END_TURN);
      if (reason.equals(BetaStopReason.MODEL_CONTEXT_WINDOW_EXCEEDED)) {
          // Obteve o máximo de tokens possível dado o tamanho da entrada
          IO.println("Generated " + tokens + " tokens (context limit reached)");
      } else if (reason.equals(BetaStopReason.MAX_TOKENS)) {
          // Obteve exatamente os tokens solicitados
          IO.println("Generated " + tokens + " tokens (max_tokens reached)");
      } else {
          // Conclusão natural
          IO.println("Generated " + tokens + " tokens (natural completion)");
      }

      return response.content().stream()
          .filter(BetaContentBlock::isText)
          .findFirst()
          .map(block -> block.asText().text())
          .orElse("");
  }
  ```

  ```php PHP
  function get_max_possible_tokens(Client $client, string $prompt): string
  {
      $response = $client->beta->messages->create(
          maxTokens: 20000,
          messages: [['role' => 'user', 'content' => $prompt]],
          model: 'claude-opus-5-5',
      );

      $tokens = $response->usage->outputTokens;
      echo match ($response->stopReason) {
          // Obteve o máximo de tokens possível dado o tamanho da entrada
          'model_context_window_exceeded' => "Generated {$tokens} tokens (context limit reached)",
          // Obteve exatamente os tokens solicitados
          'max_tokens' => "Generated {$tokens} tokens (max_tokens reached)",
          // Conclusão natural
          default => "Generated {$tokens} tokens (natural completion)",
      }, PHP_EOL;

      return array_find($response->content, static fn ($block): bool => $block->type === 'text')?->text ?? '';
  }
  ```

  ```ruby Ruby
  def get_max_possible_tokens(client, prompt)
    response = client.beta.messages.create(
      model: "claude-opus-5-5",
      max_tokens: 20000,
      messages: [{ role: "user", content: prompt }]
    )

    tokens = response.usage.output_tokens
    case response.stop_reason
    when :model_context_window_exceeded
      # Obteve o máximo de tokens possível dado o tamanho da entrada
      puts "Generated #{tokens} tokens (context limit reached)"
    when :max_tokens
      # Obteve exatamente os tokens solicitados
      puts "Generated #{tokens} tokens (max_tokens reached)"
    else
      # Conclusão natural
      puts "Generated #{tokens} tokens (natural completion)"
    end

    response.content.find { it.type == :text }.text
  end
  ```
</CodeGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Recusas e fallback" icon="arrows-clockwise" href="https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback">
    Tente novamente requisições recusadas em um modelo de fallback, no lado do servidor ou no seu cliente.
  </Card>

  <Card title="Tool runner (SDK)" icon="wrench" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner">
    Deixe o SDK gerenciar o loop de `tool_use`, a formatação de resultados e as novas tentativas para você.
  </Card>

  <Card title="Streaming de mensagens" icon="lightning" href="https://platform.claude.com/docs/pt-BR/build-with-claude/streaming">
    Leia o `stop_reason` do evento `message_delta` ao usar streaming.
  </Card>

  <Card title="Erros" icon="info" href="https://platform.claude.com/docs/pt-BR/api/errors">
    Lide com erros HTTP 4xx e 5xx, que são distintos dos motivos de parada.
  </Card>
</CardGroup>
