> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling stop reasons

> Know why a response stopped and how to handle ZylonGPT errors.

<Warning>
  **Upcoming release — Zylon 1.58**

  These 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](/en/v1.57/overview).
</Warning>

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](/en/v1.58/developer-manual/build-with-zylon/working-with-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):

```json theme={null}
{
  "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.