Handling stop reasons - Zylon

Message responses distinguish the model’s stop_reason from the overall interaction_stop_reason and error details. Check each field when deciding whether to continue, run a tool, or retry. For details about stop_reason in the response schema, see Messages.

What is `stop_reason`?

stop_reason explains how model generation ended. It is nullable and may be omitted; it is not an error type. Example response (truncated):

{
  "id": "msg_abf981cf3f1c449eacb7a85c064ca505",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Here’s a concise update..." }
  ],
  "stop_reason": "end_turn",
  "interaction_stop_reason": "stop"
}

Stop reason values

Only the six model-generation values below are stop_reason values.

stop_reason	Why it happens	What to do
`end_turn`	The model completed its response normally. Sometimes you’ll see an empty response after tool execution if you send extra user text with a `tool_result`.	Treat as complete. If empty, send only the `tool_result` block, or add a new user message like “Please continue.”
`max_tokens`	The response hit your `max_tokens` limit.	Increase `max_tokens` or ask the model to continue.
`stop_sequence`	The model generated one of your custom stop sequences.	Treat output as complete at the boundary or adjust/remove the sequence.
`tool_use`	The model wants you to run one of your custom tools. Built-in tools never stop with `tool_use`: Zylon runs them and returns `server_tool_use` blocks.	Execute the tool and return a `tool_result` block.
`pause_turn`	The model intentionally paused.	Resume the conversation when ready.
`refusal`	The model refused for safety or policy reasons.	Surface the refusal or re‑prompt with allowed content.

Interaction outcomes

interaction_stop_reason is nullable and describes the overall interaction: stop, error, cancelled, or refusal. It is separate from the model stop reason. Optional stop_details contains required type, optional category, and optional explanation; use these details when explaining an outcome to the user.

Errors

Failures before generation may return an HTTP error envelope. During streaming, handle error events; completed message objects may also include an errors array. Error types below are not valid stop_reason values. Do not retry refusals or cancellations as transient server errors.

Error type	Why it happens	What to do
`invalid_request_error`	The request inputs are invalid (e.g., artifacts not fully ingested, missing tool config, invalid IDs).	Fix inputs and retry.
`permission_error`	The token lacks access to the referenced resource.	Check org/project membership and artifact visibility.
`request_too_large`	Input size or token count exceeds model limits.	Reduce input, chunk content, or lower context size.
`api_error`	An internal server error occurred.	Retry with exponential backoff.
`overloaded_error`	The system is temporarily overloaded.	Retry with backoff and jitter.