Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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 alternativa.
Para ver el esquema completo de la respuesta, consulta la referencia de la Messages API.
| Valor | Cuándo ocurre | Qué hacer |
|---|---|---|
end_turn | Claude terminó su respuesta de forma natural. | Usa la respuesta. |
max_tokens | La respuesta alcanzó tu límite de max_tokens. | Aumenta max_tokens o continúa la respuesta. |
stop_sequence | Claude emitió una de tus stop_sequences. | Lee stop_sequence para ver cuál se activó. |
tool_use | Claude está llamando a una herramienta. | Ejecuta la herramienta y devuelve el resultado. Una llamada a herramienta de servidor a la que aún le falta su bloque de resultado se completa en una respuesta posterior. |
pause_turn | Un bucle de herramientas de servidor alcanzó su límite de iteraciones. | Envía de vuelta el contenido del asistente para continuar. |
refusal | Claude se negó a responder. | Lee stop_details y reintenta en un modelo alternativo. |
model_context_window_exceeded | La respuesta llenó la ventana de contexto del modelo. | Trata la respuesta como truncada. |
El campo stop_reason forma parte de cada respuesta exitosa de la Messages API. A diferencia de los errores, que indican fallos en el procesamiento de tu solicitud, stop_reason te indica por qué Claude completó la generación de su respuesta.
{
"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
}
}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)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 continuarClaude 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}")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 finalUna respuesta tool_use también puede contener un bloque server_tool_use cuyo id no tiene un bloque de resultado correspondiente. Esa llamada a herramienta de servidor no ha terminado, y esta respuesta no contiene 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 paralelas a herramientas: la API devuelve la respuesta sin ejecutar la herramienta de servidor para que puedas ejecutar primero las herramientas de cliente. No hay ningún otro marcador para este estado; detéctalo verificando el id de cada bloque server_tool_use o mcp_tool_use en busca de un bloque de resultado correspondiente.
{
"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 ejecución de código pausada, 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 de server_tool_use de la respuesta anterior.
{
"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, finaliza el turno del asistente; para una herramienta de servidor que Claude llamó directamente, la solicitud entonces falla con un invalid_request_error 400 que nombra la herramienta de servidor no resuelta:
`web_search` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_search_tool_result` blockOmitir 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 en su lugar. Para darle a Claude más entrada, envíala como un mensaje de usuario separado después de que el turno se complete.
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 la respuesta de vuelta tal cual. Una respuesta que deja un bloque tool_use de cliente esperando por ti nunca tiene un stop_reason de pause_turn: cuando Claude se detiene para llamar a tus herramientas, stop_reason es tool_use, y la continúas enviando los bloques tool_result de cliente en lugar de la respuesta misma.
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"}],
)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 solicitudEn 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 o Claude Opus 5 generalmente puede atenderse reintentando en otro modelo de Claude, y Rechazos y fallback muestra cómo configurar ese reintento, del lado del servidor o en tu cliente. Crédito de fallback cubre cómo evitar pagar el costo de caché de prompts dos veces cuando construyes el reintento tú mismo.
Claude se detuvo porque alcanzó el límite de la "context window" (ventana de contexto) del modelo. Esto te permite solicitar el máximo de tokens posible sin conocer el tamaño exacto de la entrada.
# Solicitud con el máximo de tokens para obtener tanto como sea 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 contextoAcostúmbrate a verificar 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:
# Manejar end_turn y otros casos
return next(
(block.text for block in response.content if block.type == "text"), ""
)Cuando una respuesta se trunca debido a 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 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 textAl 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 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 responseEs importante distinguir entre los valores de stop_reason y los errores reales:
client = anthropic.Anthropic()
try:
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
# Manejar respuesta exitosa con stop_reason
if response.stop_reason == "max_tokens":
print("Response was truncated")
except anthropic.APIStatusError as e:
# Manejar errores reales
if e.status_code == 429:
print("Rate limit exceeded")
elif e.status_code == 500:
print("Server error")Al usar streaming, stop_reason es:
null en el evento inicial message_startmessage_deltaclient = 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}")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":
# Ejecutar herramientas y continuar
tool_results = execute_tools(response.content)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
else:
# Respuesta final
return responsedef 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
# Continuar 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_responseCon la razón de detención model_context_window_exceeded, puedes solicitar el máximo de tokens posible 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 de tokens posible dado el tamaño de 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"), "")Reintenta solicitudes rechazadas en un modelo alternativo, del lado del servidor o en tu cliente.
Deja que el SDK gestione el bucle de tool_use, el formato de resultados y los reintentos por ti.
Lee stop_reason desde el evento message_delta al usar streaming.
Maneja errores HTTP 4xx y 5xx, que son distintos de las razones de detención.
Was this page helpful?