> ## Documentation Index
> Fetch the complete documentation index at: https://docket.hypertext.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Branch on the code, and handle the two that behave differently than they look.

Every failure returns an RFC 9457 problem document:

```http theme={"dark"}
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
```

```json theme={"dark"}
{
  "type": "https://docket.hypertext.studio/problems/dependency_cycle",
  "title": "That would create a loop",
  "status": 409,
  "code": "dependency_cycle",
  "detail": "..."
}
```

<Warning>
  **Branch on `code`, never on `title` or `detail`.** `code` is a closed, stable taxonomy. The
  strings are Docket's own copy, rewritten freely. Write your own.
</Warning>

A `validation_error` also includes `fieldErrors`, one stable reason code per failing field.

<Card title="Browse every problem code" icon="triangle-exclamation" href="https://docket.hypertext.studio/problems" horizontal>
  Each code, its status, and what to do. Every `type` URI resolves to a page in this catalog.
</Card>

## `not_found` can mean hidden

A 404 from `/v1/orgs/{orgId}/tasks` can mean the workspace exists and you are not a member. Never
treat it as proof of absence.

## `reauth_required` is not a sign-out

It returns 401, but the session is only too old for a high-risk action. Prompt for a passkey
step-up and retry the same request. Clear the session here and you log someone out for no reason.

## Errors over MCP

MCP tools return the same failures. Docket returns a `403` for a scope problem:

```http theme={"dark"}
WWW-Authenticate: Bearer error="insufficient_scope"
```

Re-authorize for the wider scope, then retry. See
[Authentication](/docs/developers/authentication#insufficient-scope).