Claude Platform Docs
MensagensConstruindo com Claude

Motivos de parada e fallback

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_reasonPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..

Referência rápida

ValorQuando ocorreO que fazer
end_turnClaude concluiu sua resposta naturalmente.Use a resposta.
max_tokensA resposta atingiu seu limite de max_tokens.Aumente max_tokens ou continue a resposta.
stop_sequenceClaude emitiu uma das suas stop_sequences.Leia stop_sequence para ver qual foi acionada.
tool_useClaude 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_turnUm loop de ferramenta de servidor atingiu seu limite de iterações.Envie o conteúdo do assistente de volta para continuar.
refusalClaude se recusou a responder.Leia stop_details e tente novamente em um modelo de fallback.
model_context_window_exceededA 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.

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.

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)

max_tokens

Claude parou porque atingiu o limite de max_tokensPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. especificado na sua requisição.

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

stop_sequence

Claude encontrou uma das suas sequências de paradaPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. personalizadas.

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}")

tool_use

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

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

Quando uma ferramenta de servidor ainda está aguardando

Claude pode chamar uma ferramenta de servidor e uma ferramenta de cliente (uma ferramenta que o seu código executa) no mesmo grupo de chamadas de ferramentas paralelas. 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.

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

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. A mensagem de usuário na requisição de acompanhamento tem esta aparência:

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 da ferramenta de execução de código).
  • O bloco em espera é um bloco mcp_tool_use: 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.

ErroA mensagem de erro inclui
tools não define mais a ferramenta de servidor em esperabut no `web_search` tool was provided
Texto ou outro conteúdo vem após os blocos tool_resultwas 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_resultonly 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, 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, 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 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:

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"}],
    )

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.

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.

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

Em uma recusa, o objeto stop_detailsPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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. 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 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. 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 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.

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

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:

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"),
                "",
            )

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.

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

Implemente lógica de nova tentativa para pause_turn

Quando você usa ferramentas de servidor, 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 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.

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)

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
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")

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
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}")

Padrões comuns

Lidando com fluxos de trabalho de uso de ferramentas

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

Garantindo respostas completas

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

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:

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"), "")

Próximos passos

Tente novamente requisições recusadas em um modelo de fallback, no lado do servidor ou no seu cliente.

Deixe o SDK gerenciar o loop de tool_use, a formatação de resultados e as novas tentativas para você.

Leia o stop_reason do evento message_delta ao usar streaming.

Lide com erros HTTP 4xx e 5xx, que são distintos dos motivos de parada.

Esta página foi útil?