Errors - Docket

Every failure returns an RFC 9457 problem document:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

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

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.

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

Browse every problem code

Each code, its status, and what to do. Every type URI resolves to a page in this catalog.

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

WWW-Authenticate: Bearer error="insufficient_scope"

Re-authorize for the wider scope, then retry. See Authentication.

Browse every problem code

​not_found can mean hidden

​reauth_required is not a sign-out

​Errors over MCP

`not_found` can mean hidden

`reauth_required` is not a sign-out

Errors over MCP