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

# Errors

> Stable error codes agents should handle.

Prefer structured handling. Many “errors” are **tool JSON** (`{"error":"…"}` inside MCP
content), not HTTP status codes.

## HTTP layer (`/mcp`)

| Status | `error`             | Meaning                                          | Action             |
| ------ | ------------------- | ------------------------------------------------ | ------------------ |
| `401`  | `signature_invalid` | Bad/missing signature, or user paused assistants | Fix signing / wait |
| `413`  | `payload_too_large` | Body > 256 KiB                                   | Shrink request     |

## Tool JSON codes

| Code                | Meaning                                          | Action                                                            |
| ------------------- | ------------------------------------------------ | ----------------------------------------------------------------- |
| `approval_required` | Phone prompt pending                             | Show match code; wait; [retry rules](/agent-docs/agent-docs/tools/approvals) |
| `not_approved`      | Excerpt/send retry without a valid `approval_id` | Re-prompt or stop                                                 |
| `denied`            | Policy refuse or blocked domain                  | Stop that ask; do not hammer                                      |
| `rate_limited`      | Prompts / mute / daily cap                       | Back off (`retry_after_seconds`)                                  |
| `no_answer`         | Model/extractive path found nothing safe         | Narrow the question                                               |
| `unavailable`       | Store locked / transient                         | Retry later                                                       |
| `unknown_tool`      | Name not offered                                 | `tools/list`                                                      |
| `bad_request`       | Bad arguments                                    | Fix args                                                          |

## Relay control (`/v1/*`)

| Status | `error`                           | Notes                            |
| ------ | --------------------------------- | -------------------------------- |
| `400`  | `invalid_address` / `bad_request` | Fix resolve body                 |
| `429`  | `rate_limited`                    | Often includes `Retry-After: 60` |
| `413`  | `too_large`                       | Queue envelope                   |
| `507`  | `queue_full`                      | Wait or drop                     |
| `404`  | `not_found`                       | Queue reply expired              |

Relay `429` does **not** say which limiter fired.

## TLS failures

TCP accept + TLS hang is **offline or decoy** — same class. Do not treat it as a
distinct “unregistered” signal.