Claude Platform Docs
MessagesConstruir con Claude

Razones de detención y fallback

Aprende qué significa cada valor de stop_reason y cómo manejar el truncamiento, el uso de herramientas, los turnos en pausa y los rechazos en tu aplicación.

Cada respuesta de la Messages API incluye un campo stop_reason que te indica por qué Claude dejó de generar. Revisa este campo para decidir si usar la respuesta tal cual, continuar la conversación, reintentar o recurrir a otro modelo como fallback (respaldo).

Para ver el esquema completo de la respuesta, consulta la referencia de la Messages API.

Referencia rápida

ValorCuándo ocurreQué hacer
end_turnClaude terminó su respuesta de forma natural.Usa la respuesta.
max_tokensLa respuesta alcanzó tu límite de max_tokens.Aumenta max_tokens o continúa la respuesta.
stop_sequenceClaude emitió una de tus stop_sequences.Lee stop_sequence para ver cuál se activó.
tool_useClaude está llamando a una herramienta.Ejecuta la herramienta y devuelve el resultado. Una llamada a una herramienta de servidor a la que aún le falta su bloque de resultado se completa en una respuesta posterior.
pause_turnUn bucle de herramientas de servidor alcanzó su límite de iteraciones.Envía de vuelta el contenido del asistente para continuar.
refusalClaude se negó a responder.Lee stop_details y reintenta en un modelo de fallback.
model_context_window_exceededLa respuesta llenó la ventana de contexto del modelo.Trata la respuesta como truncada.

El campo stop_reason

El campo stop_reason forma parte de cada respuesta exitosa de la Messages API. A diferencia de los errores, que indican fallos al procesar tu solicitud, stop_reason te indica por qué Claude completó la generación de su respuesta.

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 stop reason

end_turn

La razón de detención más común. Indica que Claude terminó su respuesta de forma natural.

client = anthropic.Anthropic()

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

max_tokens

Claude se detuvo porque alcanzó el límite de max_tokens especificado en tu solicitud.

client = anthropic.Anthropic()
# Solicitud con tokens limitados
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # La respuesta fue truncada
    print("Response was cut off at token limit")
    # Considera hacer otra solicitud para continuar

stop_sequence

Claude encontró una de tus secuencias de detención personalizadas.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-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á llamando a una herramienta y espera que la ejecutes.

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):
    """Execute 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",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Extrae y ejecuta la herramienta
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Devuelve el resultado a Claude para la respuesta final

Una respuesta tool_use también puede contener un bloque server_tool_use cuyo id no tiene un bloque de resultado correspondiente. Esa llamada a la herramienta de servidor no ha terminado, y esta respuesta no incluye su resultado. En el caso común, Claude llama a una herramienta de servidor y a una de tus herramientas de cliente en el mismo grupo de llamadas a herramientas en paralelo: la API retorna sin ejecutar la herramienta de servidor para que puedas ejecutar primero las herramientas de cliente. No hay otro marcador para este estado; detéctalo verificando si el id de cada bloque server_tool_use o mcp_tool_use tiene un bloque de resultado correspondiente.

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

La continuación es un mensaje de usuario de bloques tool_result, uno por cada bloque tool_use en la respuesta (consulta Manejar llamadas a herramientas), con dos reglas adicionales: ese mensaje no debe contener nada excepto los bloques tool_result, y la solicitud debe mantener el mismo array tools. Una solicitud de reanudación que ya no define la herramienta de servidor en espera falla con un 400 cuyo mensaje termina en but no `web_search` tool was provided. La API adjunta tus resultados al turno del asistente aún abierto, ejecuta la herramienta de servidor diferida (para la ejecución de código en pausa, la reanuda) y continúa el turno. Para una herramienta de servidor que Claude llamó directamente, el content de la siguiente respuesta comienza con el bloque de resultado que responde al id del server_tool_use de la respuesta anterior.

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

Agregar cualquier cosa después de los bloques tool_result en ese mensaje de usuario, como texto, termina el turno del asistente; para una herramienta de servidor que Claude llamó directamente, la solicitud entonces falla con un 400 invalid_request_error que nombra la herramienta de servidor sin resolver:

`web_search` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_search_tool_result` block

Omitir un tool_result, o colocar uno después de otro contenido, falla antes con el error estándar tool_use ids were found without tool_result blocks immediately after. Para darle más entrada a Claude, envíala como un mensaje de usuario separado después de que el turno se complete.

pause_turn

Se devuelve cuando el bucle de muestreo del lado del servidor alcanza su límite de iteraciones mientras ejecuta herramientas de servidor como la búsqueda web. El límite predeterminado es de 10 iteraciones por solicitud.

Cuando esto sucede, la respuesta puede contener un bloque server_tool_use sin un bloque de resultado correspondiente. Para permitir que Claude termine de procesar, continúa la conversación enviando de vuelta la respuesta tal cual. Una respuesta que deja un bloque tool_use de cliente esperándote nunca tiene un stop_reason de pause_turn: cuando Claude se detiene para llamar a tus herramientas, stop_reason es tool_use, y lo continúas enviando los bloques tool_result de cliente en lugar de la respuesta en sí.

response = client.messages.create(
    model="claude-opus-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":
    # Continúa la conversación enviando la respuesta de vuelta
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

refusal

Claude se negó a generar una respuesta. Los clasificadores de seguridad devuelven esta razón de detención como una respuesta HTTP 200 normal, no como un error.

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

if response.stop_reason == "refusal":
    # Claude se negó a responder
    print("Claude was unable to process this request")
    # Considera reformular o modificar la solicitud

En un rechazo, el objeto stop_details identifica la categoría de política que lo activó. Las categorías y la forma completa de la respuesta de rechazo se cubren en Rechazos y fallback. stop_details es null para todas las razones de detención distintas de refusal.

Una solicitud rechazada en Claude Fable 5.1, Claude Fable 5 o Claude Opus 5 normalmente puede atenderse reintentando en otro modelo Claude. Rechazos y fallback muestra cómo configurar ese reintento, del lado del servidor o en tu cliente. Si construyes el reintento tú mismo desde Claude Fable 5.1, Claude Fable 5 o Claude Opus 5, crédito de fallback cubre cómo evitar pagar dos veces el costo de la caché de prompts.

model_context_window_exceeded

Claude se detuvo porque alcanzó el límite de la ventana de contexto del modelo. Esto te permite solicitar el máximo posible de tokens sin conocer el tamaño exacto de la entrada.

# Solicitud con el máximo de tokens para obtener lo más posible
response = client.beta.messages.create(
    model="claude-opus-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":
    # La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
    print("Response reached model's context window limit")
    # La respuesta sigue siendo válida, pero fue limitada por la ventana de contexto

Mejores prácticas para manejar las razones de detención

Siempre revisa stop_reason

Acostúmbrate a revisar el stop_reason en tu lógica de manejo de respuestas:

def handle_response(response):
    if response.stop_reason == "tool_use":
        return handle_tool_use(response)
    elif response.stop_reason == "max_tokens":
        return handle_truncation(response)
    elif response.stop_reason == "model_context_window_exceeded":
        return handle_context_limit(response)
    elif response.stop_reason == "pause_turn":
        return handle_pause(response)
    elif response.stop_reason == "refusal":
        return handle_refusal(response)
    else:
        # Maneja end_turn y otros casos
        return next(
            (block.text for block in response.content if block.type == "text"), ""
        )

Maneja las respuestas truncadas con elegancia

Cuando una respuesta se trunca debido a los límites de tokens o a la ventana de contexto, agrega un aviso para que el lector sepa que la salida está incompleta. Para continuar generando desde donde se quedó la respuesta, consulta Asegurar respuestas 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

Implementa lógica de reintento para pause_turn

Al usar herramientas de servidor, la API puede devolver pause_turn si el bucle de muestreo del lado del servidor alcanza su límite de iteraciones (10 por defecto). Maneja esto continuando la conversación:

def handle_server_tool_conversation(client, user_query, tools, max_continuations=5):
    """
    Handle server tool conversations that may require multiple continuations.

    The server runs a sampling loop when executing server tools. If the loop
    reaches its iteration limit, the API returns pause_turn. Continue the
    conversation by sending the response back to let Claude finish.
    """
    messages = [{"role": "user", "content": user_query}]

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

        if response.stop_reason != "pause_turn":
            # Claude terminó de procesar - devuelve la respuesta final
            return response

        # pause_turn: reemplaza la lista completa de mensajes para mantener los roles alternados
        messages = [
            {"role": "user", "content": user_query},
            {"role": "assistant", "content": response.content},
        ]

    # Se alcanzó el máximo de continuaciones - devuelve la última respuesta
    return response

Razones de detención vs. errores

Es importante distinguir entre los valores de stop_reason y los errores reales:

Razones de detención (respuestas exitosas)

  • Forman parte del cuerpo de la respuesta
  • Indican por qué la generación se detuvo normalmente
  • La respuesta contiene contenido válido

Errores (solicitudes fallidas)

  • Códigos de estado HTTP 4xx o 5xx
  • Indican fallos en el procesamiento de la solicitud
  • La respuesta contiene detalles del error
client = anthropic.Anthropic()

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

    # Maneja la respuesta exitosa con stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Maneja los errores reales
    if e.status_code == 429:
        print("Rate limit exceeded")
    elif e.status_code == 500:
        print("Server error")

Consideraciones sobre streaming

Al usar streaming, stop_reason:

  • Es null en el evento inicial message_start
  • Se proporciona en el evento message_delta
  • No se proporciona en ningún otro evento
client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-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}")

Patrones comunes

Manejo de flujos de trabajo de uso de herramientas

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

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

        if response.stop_reason == "tool_use":
            # Ejecuta las herramientas y continúa
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Respuesta final
            return response

Asegurar respuestas 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", 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

        # Continúa desde donde se quedó
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Obtener el máximo de tokens sin conocer el tamaño de la entrada

Con la razón de detención model_context_window_exceeded, puedes solicitar el máximo posible de tokens sin calcular el tamaño de la 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",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    if response.stop_reason == "model_context_window_exceeded":
        # Se obtuvo el máximo posible de tokens dado el tamaño de la entrada
        print(
            f"Generated {response.usage.output_tokens} tokens (context limit reached)"
        )
    elif response.stop_reason == "max_tokens":
        # Se obtuvieron exactamente los tokens solicitados
        print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
    else:
        # Finalización 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 pasos

Rechazos y fallback

Reintenta las solicitudes rechazadas en un modelo de fallback, del lado del servidor o en tu cliente.

Tool Runner (SDK)

Deja que el SDK gestione el bucle de tool_use, el formato de los resultados y los reintentos por ti.

Mensajes en streaming

Lee stop_reason del evento message_delta al usar streaming.

Errores

Maneja los errores HTTP 4xx y 5xx, que son distintos de las razones de detención.

Was this page helpful?