Motivos de parada

Cuando llamas al endpoint de Messages, cada respuesta incluye un stop_reason que explica por qué el modelo se detuvo. Manejar bien este campo es clave para crear aplicaciones fiables. Para ver stop_reason en el esquema de respuesta, revisa Mensajes.

¿Qué es `stop_reason`?

stop_reason aparece en cada respuesta exitosa. No es un error: indica cómo terminó la generación. Ejemplo de respuesta (truncada):

{
  "id": "msg_abf981cf3f1c449eacb7a85c064ca505",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Aquí tienes un resumen..." }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null
}

Valores de `stop_reason`

Cuando una petición falla, el stop reason coincide con uno de los valores de error de la tabla y la respuesta se entrega como un objeto de error.

stop_reason	Por qué ocurre	Qué hacer
`end_turn`	El modelo terminó normalmente. A veces llega vacío después de un `tool_result` si envías texto adicional junto al bloque `tool_result`.	Trátalo como completo. Si viene vacío, envía solo el `tool_result` o añade un nuevo mensaje como “Continúa”.
`max_tokens`	La respuesta llegó al límite de `max_tokens`.	Aumenta `max_tokens` o pide continuar.
`stop_sequence`	Se generó una secuencia de parada configurada por ti.	Considera la salida completa en ese punto o ajusta la secuencia.
`tool_use`	El modelo necesita que ejecutes una herramienta.	Ejecuta la herramienta y devuelve un bloque `tool_result`.
`pause_turn`	El modelo pausó la conversación.	Continúa cuando estés listo.
`refusal`	El modelo se negó por razones de seguridad o políticas.	Muestra la negativa o re‑formula con contenido permitido.
`invalid_request_error`	Entradas inválidas (artefactos sin ingesta completa, configuración de herramientas inexistente, IDs incorrectos).	Corrige la entrada y reintenta.
`permission_error`	El token no tiene acceso al recurso referenciado.	Revisa la pertenencia a la organización/proyecto y la visibilidad del artefacto.
`request_too_large`	La entrada excede límites de tamaño o tokens.	Reduce la entrada, divide el contenido o baja el contexto.
`api_error`	Error interno del servidor.	Reintenta con backoff exponencial.
`overloaded_error`	El sistema está temporalmente sobrecargado.	Reintenta con backoff y algo de jitter (aleatorización).

​¿Qué es stop_reason?

​Valores de stop_reason

¿Qué es `stop_reason`?

Valores de `stop_reason`