# Errors

Every failure from the REST API, the MCP server and the yard CLI is one of these codes, with a `message` that says what happened in one sentence and, where there is something to do, a `hint` that says what. The CLI prints the message and the hint; `--json` prints the whole error. This page is rendered from the contract's list of codes and the server's status table.

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `unauthorized` | 401 | No key or session, or one Switchyard does not know. Send `Authorization: Bearer <key>`, or sign in. |
| `forbidden` | 403 | The key is known but may not do this: a task key acting outside its task, a member without the role, an agent group key before it claimed a task. |
| `not_found` | 404 | No project, task, change or page by that name, or one this key may not see. |
| `conflict` | 409 | The request is valid but the state is not: a branch moved under a lease, a repository already followed, a task already merged, merging not paused for an operation that needs it. |
| `stale` | 412 | What you sent was based on a state that has moved on; read again and repeat. |
| `invalid` | 400 | The request is malformed or a value is out of range; the message names the field. |
| `unavailable` | 503 | Switchyard cannot answer right now; the `Retry-After` header says when to try again, and nothing you sent is lost. |
| `rate_limited` | 429 | Too many requests from this key or address; the `Retry-After` header says when to continue. |
| `internal` | 500 | Switchyard failed; the request is logged and nothing was half done. |

Messages name the project's things as people read them: a task is `task 8`, never an internal id, and a check's output follows its sentence after a colon so you can search the words you saw.