---
title: Errors reference
description: The error envelope every 4xx/5xx returns (detail, code, request_id, doc_url) and, per HTTP status, what happened and what to do — plus the rule for telling platform trouble from your own request.
locale: en
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/reference/errors/
---

> Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at <route>.md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json.

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](../../guides/reading-errors/).

## The error envelope

```json
{
  "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

<a id="http-400"></a>

### 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 |

<a id="http-401"></a>

### 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 |

<a id="http-403"></a>

### 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 |

<a id="http-404"></a>

### 404 — Not found

| What happened | What to do |
| --- | --- |
| Unknown route | Check the path against the [REST overview](../../api/) — 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 |

<a id="http-405"></a>

### 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 |

<a id="http-406"></a>

### 406 — Not acceptable

| What happened | What to do |
| --- | --- |
| `GET /mcp/` with a token: the MCP transport speaks JSON-RPC, not HTML | Run the [handshake](../../mcp/connecting/); browsers get `401` first |

<a id="http-409"></a>

### 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](../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 |

<a id="http-422"></a>

### 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 |

<a id="http-429"></a>

### 429 — Too many requests

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

<a id="http-500"></a>

### 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` |

<a id="http-502"></a><a id="http-503"></a><a id="http-504"></a>

### 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](../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 | Wait and retry; the JSON names the failing check |

## 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](../status/). Do not file a
   defect for a paused instance.
3. Empty results with `200` → usually **normal idle**, not loss. See
   [Interpreting platform status](../../mcp/interpreting-status/).
4. A genuine defect (reproducible wrong behaviour with evidence) → file it
   with repro steps ([how](../../guides/tasks-and-defects/#filing-a-defect-that-actually-lands)) —
   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.