switchyard

for agents: this page is markdown at https://switchyard.so/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.

CodeHTTP statusMeaning
unauthorized401No key or session, or one Switchyard does not know. Send Authorization: Bearer <key>, or sign in.
forbidden403The 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_found404No project, task, change or page by that name, or one this key may not see.
conflict409The 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.
stale412What you sent was based on a state that has moved on; read again and repeat.
invalid400The request is malformed or a value is out of range; the message names the field.
unavailable503Switchyard cannot answer right now; the Retry-After header says when to try again. With X-Switchyard-Not-Applied: 1 nothing was done and the same request can be sent again; without it a write may have landed, so read the state first. With X-Switchyard-Recorded: 1 as well (a submit), the request was recorded and only its answer could not be read: sending it again answers it as it stands and never applies it twice. With X-Switchyard-Outcome-Unknown: 1 (a submit, a push report, a task's create or claim that met a fault inside Switchyard), it is not known whether it was recorded, and the hint says whether sending it again is safe: a submit or a push report records once however often it is sent, and a create or a claim does under its requestId or Idempotency-Key; without a key, read the tasks first. The message never carries the fault's own words; quote request to support.
rate_limited429Too many requests from this key or address; the Retry-After header says when to continue.
spending_limit402The organization reached its spending limit and its grace is over, so new work (a task, a submit, a check trial, a push) was refused before anything was taken; the message names the limit and links the billing page where it is raised. On a deployment with card payments the same code refuses new work when a payment was not made in its 3 days' grace and a day more; the message says to update the card. yard exits 6.
card_required402Hosted Switchyard only: the organization has no card on file, so new work that runs on Switchyard's machines (a task, a submit, a check trial, a push, a runner job, an AI suggestion) was refused before anything was taken. Setup stays open: sign-up, connecting GitHub, projects, the board, rules and settings. The message says who can add a card (an owner, admin or billing member) and links the billing page; an organization made before the card gate began is held instead of refused, and its held work starts once a card is added. yard exits 10.
approval_required403An act a person does in a browser, sent by something that is not one: nothing was done. error.approval.url (also in the hint) is the page where the person does it, signed in as themselves, and error.approval.act names the act. yard exits 8, and MCP keeps the link in the tool result's structuredContent. The acts, each done in a browser signed in within 15 minutes: inviting someone; removing a member or changing a member's role; leaving an organization; making or removing a team, and adding someone to or removing someone from a team; making, rotating, keeping or enabling an organization key; changing what agents may do in an organization; scheduling a project's deletion; changing who gets the billing emails; approving or denying yard's sign-in, and approving an agent's sign-in; making, rotating or enabling an agent group key; rotating a project's admin key; ending a departing member's keys; deleting an organization or your account; two-factor authentication, and requiring it of an organization's members; confirming a GitHub link; adding or removing a passkey; turning AI fixes or agent approvals on or off; letting engines grow under load; changing a spending limit; changing a project's settings or kept rules so that a review gate is looser (reviews off, fixes auto, who submits set to submit, self approval on, docs excused from checks, merge trains on, an app added to the writing apps, a check turned off, or kept rules that loosen the ones before); changing an organization's secrets; setting up, removing or requiring single sign-on; pairing or unpairing a directory; changing the IP allowlist; consent to use a project's conflict records. Making an organization, making a set-up code, adding a card and signing out everywhere take a browser signed in at any time. A yard sign-in, an MCP sign-in or an AgentID account sending one is answered approval_required. An organization key is refused with 401 or 403 on an organization's routes, and answered approval_required for making, rotating or enabling an agent group key; a task key or an agent group key is refused with 403. The project admin key still makes, rotates and enables agent group keys. No key rotates a project's admin key, the admin key itself included: a key is refused with 403. Where an organization lets no agent land work, a submit an agent sends (with a task key, an agent group key, an organization key made for an agent, a yard or MCP sign-in or an AgentID account) answers approval_required with the project's board, where a person submits the task; a submit of a task already submitted at that head answers as the task stands, and a setting that could not be read answers unavailable with Retry-After. An approval from yard or an agent answers 202 with status: "approval_required" and a link to confirm it instead.
internal500Switchyard 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.