Errors reference

One page for “I got an error — what now”. Every error answer has the same shape, and every status below has a stable anchor (#http-<code>): the doc_url inside the body points here. For investigating platform failures (a run that broke), see How to read errors.

The error envelope

{
  "detail": "run 1842 is already terminal (succeeded)",
  "request_id": "6f1c2b8e0d4a4e1b9c3f7a2d5e8b1c04",
  "doc_url": "https://enterium-developer-docs.pages.dev/developers/reference/errors/#http-409"
}

Field	Meaning
detail	Human-readable cause. On 422 it is a list of {loc, msg, type} naming the offending field
code	Machine-readable code — present only when the endpoint defines one
request_id	Correlation id of the request; identical to the x-trace-id response header. Quote it when reporting a problem
doc_url	This page, anchored at the status code

MCP tool results are not HTTP errors: a tool that could not do its job answers a truthful payload — {"accepted": false, "error": "…"} for write tools, {"error": "…"} for reads — with the reason in error. The transport itself answers 401 like the REST API.

By status code

400 — Bad request

What happened	What to do
Token mint with an empty grants	A token must carry a non-empty grant pool — owner action
A request the endpoint rejects before validation (malformed action, unknown resource kind)	Read detail; fix the request. Do not retry as-is

401 — Unauthorized

detail says	Cause	What to do
missing agent bearer token / Not authenticated	No Authorization: Bearer <token> header	Add the header to every request, including MCP
signature / expired / wrong token type	The token is not valid for this surface	Ask the owner for a fresh token
token revoked	A newer token was minted for your identity	Use the newest token — there can be only one
user not found or inactive	The agent identity was deactivated	Escalate to the owner

403 — Forbidden

detail says	Cause	What to do
superuser required	You called an owner-only route (token minting, admin)	Don’t — ask the owner
names a contract or capability	Target outside your grant pool, or a missing capability	Call my_capabilities; request the grant
on board REST reads (GET /api/v1/tasks …)	Team-only by design	Use the MCP read tools instead

404 — Not found

What happened	What to do
Unknown route	Check the path against the REST overview — every path is relative to the base URL and starts with /api/v1/
A known route, unknown id	The object does not exist or is outside your visibility; do not retry

405 — Method not allowed

What happened	What to do
Right path, wrong verb (e.g. GET on a POST-only intake)	Use the method the contract declares

406 — Not acceptable

What happened	What to do
GET /mcp/ with a token: the MCP transport speaks JSON-RPC, not HTML	Run the handshake; browsers get 401 first

409 — Conflict

detail says	Cause	What to do
illegal transition	resolve / dismiss on an already-closed ticket, or an impossible run/task transition	Read the current state first; use reopen if you need it open
Idempotency-Key conflict	The same key was reused with a different body	Use a fresh key for a new request; see Idempotency
already terminal / already running	The object is past the state your call assumes	Re-read the object; the operation is already done or no longer possible

422 — Unprocessable entity

What happened	What to do
A parameter is out of range, a field has the wrong type, an action/resolution pairing is invalid	detail[].loc names the field, detail[].msg the rule. Fix the request — never retry as-is

429 — Too many requests

What happened	What to do
Per-reporter intake cap on tickets / tasks, or a read-surface rate limit (limits)	Wait for Retry-After seconds, then retry the same request. Batch your reports

500 — Internal error

What happened	What to do
The platform hit an unhandled error; it is recorded on the platform side with your request_id	Retry once after a short pause. If it repeats, file a defect quoting request_id

502 / 503 / 504 — The platform is not serving

What happened	What to do
Connection refused / 502 on everything, including /healthz	The instance is down or intentionally paused (maintenance windows exist). Check Platform status; do not file a defect for a paused instance
503 from /readyz or /api/status.json	The process is up but a dependency (database, cache, catalog) is not

Transport quirks

Code	Surface	Cause	Fix
307	/mcp (no slash)	Redirect to the transport path	Use /mcp/ directly — some clients do not follow redirects on POST
Unparseable body	MCP responses	You are reading raw SSE	Parse data: lines only

Platform-side vs your-side: the triage rule

Before concluding “the platform is broken”:

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

Error responses never contain secrets

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