for agents: this page is markdown at https://switch-yard.dev/docs/errors.md; every page is listed in llms.txt.

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.