Errors and headers

#The error shape

{
  "error": {
    "type": "agent_stopped",
    "message": "this agent is stopped under an owner hold, so nothing it sends goes upstream and nothing was sent; the person it acts for, an owner or an admin can restart it in the console under Agents",
    "hold": "owner",
    "stopped": "agent",
    "agentId": "agt_4f2c91a7",
    "fix": "Stop: the kill switch is on (error.hold says which hold, error.message who may lift it). Do not retry; tell the person you act for.",
    "docs": "https://immiscible.fly.dev/docs/guides/kill-switch#what-a-stop-stops",
    "requestId": "d210346a-c44e-4be8-bca7-1d8503868ce8"
  }
}

requestId is the same id as the x-request-id response header, on every error: quote it when you write to us and we can find the request. Every 4xx carries fix, one sentence saying what to send differently, and docs, the page that explains it, so an agent can correct its next request from the error alone. Both are additions to the shape your client already reads; a route that has its own more specific fix keeps it. On the MCP server, JSON-RPC errors carry them in error.data, and a refused tool call puts them in the tool result’s text.

A validation failure also lists each problem with the field it is about, so a form can mark the field. message joins them with “; “:

{
  "error": {
    "type": "invalid_request",
    "message": "summary is required: say in one sentence what the agent is about to do; payment.amount must be a whole number of minor units (pence) above zero, for example 6420 for £64.20",
    "errors": [
      { "field": "summary", "message": "summary is required: say in one sentence what the agent is about to do" },
      { "field": "payment.amount", "message": "payment.amount must be a whole number of minor units (pence) above zero, for example 6420 for £64.20" }
    ]
  }
}

field is a dotted path into the body, or null when the problem is the body as a whole. invalid_request, invalid_mandate, invalid_budget and the other validation types (invalid_application, invalid_upstream) carry errors.

Every response, error or not, carries an x-request-id header. It is the id of the request in our logs: quote it when you ask for help with one.

On Anthropic-shaped routes errors use Anthropic’s envelope ({ "type": "error", "error": { ... } }), so SDK error handling keeps working. error.type is stable and safe to branch on; error.message is for people and may change. Some refusals carry the numbers a client needs to act (for example oldCount and newCount on selection_changed). Every refusal that reflects a policy decision carries an evidenceRecord id: the refusal itself is in the ledger.

#Common to every route

#The gate

#The gateway

#Machine admin

#Headers

#Request

#Response