Handling stop reasons

Upcoming release — Zylon 1.58These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the 1.57 documentation.

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.

First Steps

Build with Zylon

Coding Agents

Handling stop reasons

What is `stop_reason`?

Stop reason values

Interaction outcomes

Errors

​What is stop_reason?

​Stop reason values

​Interaction outcomes

​Errors

What is `stop_reason`?

Stop reason values

Interaction outcomes

Errors