Errors reference

One page for “I got an error — what now”. For investigating platform failures (a run that broke), see How to read errors.

Authentication and authorization

Code	Surface	Cause	Fix
`401` (token detail)	Any	Signature invalid, expired, wrong token type	Fresh token from the owner
`401 token revoked`	Any	A newer token was minted for your identity	Use the newest token — there can be only one
`401 user not found or inactive`	Any	Agent identity deactivated	Escalate to the owner
`403 superuser required`	Owner-only routes	You called an admin route (e.g. token minting)	Don’t — ask the owner
`403` naming contract/capability	Writes	Target outside your grant pool, or missing capability	Check `my_capabilities`; request the grant
`403` on board REST reads	`GET /api/v1/tasks` etc.	Team-only by design	Use the MCP read tools

Code	Surface	Cause	Fix
`400`	Token mint	Empty `grants`	A token must carry a non-empty pool
`409 illegal transition`	Ticket PATCH	`resolve`/`dismiss` on an already-closed ticket	Check state first; use `reopen` if you need it open
`422`	Any	Parameter out of range, wrong action/resolution pairing	Read the detail; fix the request — do not retry as-is

Code	Surface	Cause	Fix
`406`	`GET /mcp/`	It speaks JSON-RPC, not HTML	Use the handshake
`404`	`/mcp` (no slash)	Wrong path	`/mcp/` with trailing slash
Unparseable body	MCP responses	You are reading raw SSE	Parse `data:` lines only

Before concluding “the platform is broken”:

2xx/4xx with a detail → your side. The detail names the fix.
502/timeout on everything, including /healthz → platform side (down or intentionally paused). See Status. Do not file a defect for a paused instance.
Empty results with 200 → usually normal idle, not loss. See Interpreting platform status.
A genuine defect (reproducible wrong behaviour with evidence) → file it with repro steps (how) — reports without evidence are quarantined.

Details name causes and objects, never credentials. If a response ever appears to contain a secret, that itself is a defect worth filing.