Manejo de razones de parada
Cuando realizas una solicitud a la API de Messages, la respuesta de Claude incluye un campo stop_reason que indica por qué el modelo dejó de generar su respuesta. Entender estos valores es crucial para construir aplicaciones robustas que manejen diferentes tipos de respuesta de manera apropiada.
Para detalles sobre stop_reason en la respuesta de la API, consulta la referencia de la API de Messages.
¿Qué es stop_reason?
El campo stop_reason es parte de cada respuesta exitosa de la API de Messages. A diferencia de los errores, que indican fallas en el procesamiento de tu solicitud, stop_reason te dice por qué Claude completó exitosamente la generación de su respuesta.
{
"id": "msg_01234",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Aquí está la respuesta a tu pregunta..."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 100,
"output_tokens": 50
}
}Valores de razón de parada
end_turn
La razón de parada más común. Indica que Claude terminó su respuesta de manera natural.
if response.stop_reason == "end_turn":
# Procesar la respuesta completa
print(response.content[0].text)Respuestas vacías con end_turn
A veces Claude devuelve una respuesta vacía (exactamente 2-3 tokens sin contenido) con stop_reason: "end_turn". Esto típicamente ocurre cuando Claude interpreta que el turno del asistente está completo, particularmente después de resultados de herramientas.
Causas comunes:
- Agregar bloques de texto inmediatamente después de resultados de herramientas (Claude aprende a esperar que el usuario siempre inserte texto después de resultados de herramientas, por lo que termina su turno para seguir el patrón)
- Enviar la respuesta completada de Claude de vuelta sin agregar nada (Claude ya decidió que terminó, por lo que permanecerá terminado)
Cómo prevenir respuestas vacías:
# INCORRECTO: Agregar texto inmediatamente después de tool_result
messages = [
{"role": "user", "content": "Calcula la suma de 1234 y 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": "Aquí está el resultado" # No agregues texto después de tool_result
}
]}
]
# CORRECTO: Enviar resultados de herramientas directamente sin texto adicional
messages = [
{"role": "user", "content": "Calcula la suma de 1234 y 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"
}
]} # Solo el tool_result, sin texto adicional
]
# Si aún obtienes respuestas vacías después de corregir lo anterior:
def handle_empty_response(client, messages):
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=messages
)
# Verificar si la respuesta está vacía
if (response.stop_reason == "end_turn" and
not response.content:
# INCORRECTO: No simplemente reintentar con la respuesta vacía
# Esto no funcionará porque Claude ya decidió que terminó
# CORRECTO: Agregar un prompt de continuación en un NUEVO mensaje de usuario
messages.append({"role": "user", "content": "Por favor continúa"})
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
messages=messages
)
return responseMejores prácticas:
- Nunca agregues bloques de texto inmediatamente después de resultados de herramientas - Esto enseña a Claude a esperar entrada del usuario después de cada uso de herramienta
- No reintentes respuestas vacías sin modificación - Simplemente enviar la respuesta vacía de vuelta no ayudará
- Usa prompts de continuación como último recurso - Solo si las correcciones anteriores no resuelven el problema
max_tokens
Claude se detuvo porque alcanzó el límite de max_tokens especificado en tu solicitud.
# Solicitud con tokens limitados
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=10,
messages=[{"role": "user", "content": "Explica la física cuántica"}]
)
if response.stop_reason == "max_tokens":
# La respuesta fue truncada
print("La respuesta fue cortada en el límite de tokens")
# Considera hacer otra solicitud para continuarstop_sequence
Claude encontró una de tus secuencias de parada personalizadas.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
stop_sequences=["FIN", "PARAR"],
messages=[{"role": "user", "content": "Genera texto hasta que digas FIN"}]
)
if response.stop_reason == "stop_sequence":
print(f"Se detuvo en la secuencia: {response.stop_sequence}")tool_use
Claude está llamando a una herramienta y espera que la ejecutes.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[weather_tool],
messages=[{"role": "user", "content": "¿Cómo está el clima?"}]
)
if response.stop_reason == "tool_use":
# Extraer y ejecutar la herramienta
for content in response.content:
if content.type == "tool_use":
result = execute_tool(content.name, content.input)
# Devolver resultado a Claude para respuesta finalpause_turn
Usado con herramientas de servidor como búsqueda web cuando Claude necesita pausar una operación de larga duración.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
tools=[{"type": "web_search_20250305", "name": "web_search"}],
messages=[{"role": "user", "content": "Busca las últimas noticias de IA"}]
)
if response.stop_reason == "pause_turn":
# Continuar la conversación
messages = [
{"role": "user", "content": original_query},
{"role": "assistant", "content": response.content}
]
continuation = client.messages.create(
model="claude-sonnet-4-5",
messages=messages,
tools=[{"type": "web_search_20250305", "name": "web_search"}]
)refusal
Claude se negó a generar una respuesta debido a preocupaciones de seguridad.
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=[{"role": "user", "content": "[Solicitud insegura]"}]
)
if response.stop_reason == "refusal":
# Claude se negó a responder
print("Claude no pudo procesar esta solicitud")
# Considera reformular o modificar la solicitudSi encuentras razones de parada refusal frecuentemente mientras usas Claude Sonnet 4.5 u Opus 4.1, puedes intentar actualizar tus llamadas a la API para usar Sonnet 4 (claude-sonnet-4-20250514), que tiene diferentes restricciones de uso. Aprende más sobre entender los filtros de seguridad de la API de Sonnet 4.5.
Para aprender más sobre rechazos activados por filtros de seguridad de la API para Claude Sonnet 4.5, consulta Entendiendo los Filtros de Seguridad de la API de Sonnet 4.5.
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 de tokens posibles sin conocer el tamaño exacto de la entrada.
# Solicitud con tokens máximos para obtener tanto como sea posible
response = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=64000, # Tokens máximos de salida del modelo
messages=[{"role": "user", "content": "Entrada grande que usa la mayor parte de la ventana de contexto..."}]
)
if response.stop_reason == "model_context_window_exceeded":
# La respuesta alcanzó el límite de la ventana de contexto antes de max_tokens
print("La respuesta alcanzó el límite de la ventana de contexto del modelo")
# La respuesta sigue siendo válida pero fue limitada por la ventana de contextoEsta razón de parada está disponible por defecto en Sonnet 4.5 y modelos más nuevos. Para modelos anteriores, usa el encabezado beta model-context-window-exceeded-2025-08-26 para habilitar este comportamiento.
Mejores prácticas para manejar razones de parada
1. Siempre verificar stop_reason
Haz un hábito de 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 response.content[0].text2. Manejar respuestas truncadas con gracia
Cuando una respuesta es truncada debido a límites de tokens o ventana de contexto:
def handle_truncated_response(response):
if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
# Opción 1: Advertir al usuario sobre el límite específico
if response.stop_reason == "max_tokens":
message = "[Respuesta truncada debido al límite de max_tokens]"
else:
message = "[Respuesta truncada debido al límite de ventana de contexto]"
return f"{response.content[0].text}\n\n{message}"
# Opción 2: Continuar generación
messages = [
{"role": "user", "content": original_prompt},
{"role": "assistant", "content": response.content[0].text}
]
continuation = client.messages.create(
model="claude-sonnet-4-5",
max_tokens=1024,
messages=messages + [{"role": "user", "content": "Por favor continúa"}]
)
return response.content[0].text + continuation.content[0].text3. Implementar lógica de reintento para pause_turn
Para herramientas de servidor que pueden pausar:
def handle_paused_conversation(initial_response, max_retries=3):
response = initial_response
messages = [{"role": "user", "content": original_query}]
for attempt in range(max_retries):
if response.stop_reason != "pause_turn":
break
messages.append({"role": "assistant", "content": response.content})
response = client.messages.create(
model="claude-sonnet-4-5",
messages=messages,
tools=original_tools
)
return responseRazones de parada vs. errores
Es importante distinguir entre valores de stop_reason y errores reales:
Razones de parada (respuestas exitosas)
- 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 fallas en el procesamiento de solicitudes
- La respuesta contiene detalles del error
try:
response = client.messages.create(...)
# Manejar respuesta exitosa con stop_reason
if response.stop_reason == "max_tokens":
print("La respuesta fue truncada")
except anthropic.APIError as e:
# Manejar errores reales
if e.status_code == 429:
print("Límite de tasa excedido")
elif e.status_code == 500:
print("Error del servidor")Consideraciones de streaming
Cuando usas streaming, stop_reason es:
nullen el evento inicialmessage_start- Proporcionado en el evento
message_delta - No proporcionado en ningún otro evento
with client.messages.stream(...) as stream:
for event in stream:
if event.type == "message_delta":
stop_reason = event.delta.stop_reason
if stop_reason:
print(f"Stream terminó con: {stop_reason}")Patrones comunes
Manejar 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-sonnet-4-5",
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 responseAsegurar 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-sonnet-4-5",
messages=messages,
max_tokens=4096
)
full_response += response.content[0].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": "Por favor continúa desde donde te quedaste."}
]
return full_responseObtener tokens máximos sin conocer el tamaño de entrada
Con la razón de parada model_context_window_exceeded, puedes solicitar el máximo de tokens posibles sin calcular el tamaño de entrada:
def get_max_possible_tokens(client, prompt):
"""
Obtener tantos tokens como sea posible dentro de la ventana de contexto del modelo
sin necesidad de calcular el conteo de tokens de entrada
"""
response = client.messages.create(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": prompt}],
max_tokens=64000 # Establecer a los tokens máximos de salida del modelo
)
if response.stop_reason == "model_context_window_exceeded":
# Obtuvo el máximo de tokens posibles dado el tamaño de entrada
print(f"Generó {response.usage.output_tokens} tokens (límite de contexto alcanzado)")
elif response.stop_reason == "max_tokens":
# Obtuvo exactamente los tokens solicitados
print(f"Generó {response.usage.output_tokens} tokens (max_tokens alcanzado)")
else:
# Completación natural
print(f"Generó {response.usage.output_tokens} tokens (completación natural)")
return response.content[0].textAl manejar apropiadamente los valores de stop_reason, puedes construir aplicaciones más robustas que manejen con gracia diferentes escenarios de respuesta y proporcionen mejores experiencias de usuario.