# Error & finish/stop reasons

> Dialect error envelopes and the universal finish_reason / stop_reason mapping catalog.

Cross-dialect mapping used when **translating** responses. Passthrough preserves upstream bodies and finish fields as-is.

## Canonical stop reasons

| Canonical | Meaning |
|-----------|---------|
| `end_turn` | Normal completion |
| `max_tokens` | Hit length / token limit |
| `tool_use` | Model requested tool call(s) |
| `stop_sequence` | Hit a stop sequence |
| `refusal` | Safety / content filter / refusal |

## Google `finishReason` → canonical

| Google | Canonical |
|--------|-----------|
| `STOP`, `STOP_SEQUENCE` | `end_turn` |
| `MAX_TOKENS`, `LENGTH` | `max_tokens` |
| `SAFETY`, `RECITATION`, `BLOCKLIST`, `PROHIBITED_CONTENT`, `SPII`, `CONTENT_FILTER` | `refusal` |
| `MALFORMED_FUNCTION_CALL` | `tool_use` |
| `OTHER`, empty, unspecified | `end_turn` |
| Any candidate with `functionCall` parts | `tool_use` (overrides STOP) |

## OpenAI `finish_reason` → canonical

| OpenAI | Canonical |
|--------|-----------|
| `stop` | `end_turn` |
| `length` | `max_tokens` |
| `tool_calls` / `function_call` | `tool_use` |
| `content_filter` | `refusal` |

## Anthropic `stop_reason` → canonical

| Anthropic | Canonical |
|-----------|-----------|
| `end_turn` | `end_turn` |
| `max_tokens` | `max_tokens` |
| `tool_use` | `tool_use` |
| `stop_sequence` | `stop_sequence` |
| `refusal` | `refusal` |

## Error envelopes

| Dialect | Shape |
|---------|-------|
| OpenAI | `{"error":{"message","type","code"}}` |
| Anthropic | `{"type":"error","error":{"type","message"}}` |
| Google | `{"error":{"code","message","status"}}` |

On translate, upstream errors are reshaped into the **client dialect**. On passthrough, the upstream body is relayed.

## Gateway-specific codes

| Code | Meaning |
|------|---------|
| `unsupported_realtime_bridge` | Cross-protocol Realtime ↔ Live attempt |
| `unsupported_provider_capability` | Capability flag off (e.g. media on openai_compat) |
| Tool kind errors | Anthropic/Google translate rejected non-function tools |

## Related

- [SSE protocol catalog](/llm-gateway/reference/sse-protocol/)  
- [Tools policy](/llm-gateway/guides/tools-policy/)