Errors

Stable public categories so clients can handle failure without guessing.

Examples below are synthetic. Do not paste production tokens or tenant hostnames into tickets.

Categories

Category	Typical HTTP	What it means for the caller
Unauthenticated	`401`	Missing/invalid Bearer; follow `WWW-Authenticate` / resource metadata
Forbidden	`403`	Authenticated but scope, pack, or write consent insufficient
Not ready	`503` (or client sees failed `/ready`)	Process up but not safe to send traffic yet
Rate limited	`429`	Slow down and retry with backoff
Invalid arguments	`400` / tool error	Zod/schema validation failed — fix args from the tool schema
Upstream / peer unavailable	`502` / `503`	Ledger peer path unavailable — retry later; do not spin hot
Internal	`500`	Unexpected failure — retry with backoff; contact operator if persistent

Tool-level errors surface as MCP tool results with structured messages suitable for an LLM. Prefer the category table over scraping prose.

Synthetic examples

401 — missing bearer

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer FAKESECRET_g3h4i5j6k7l8m9n0o1p2="https://legate.example.internal/.well-known/oauth-protected-resource"

403 — write without consent

{
  "error": "forbidden",
  "category": "forbidden",
  "message": "Write consent required for prepare_transaction"
}

429 — rate limited

{
  "error": "rate_limited",
  "category": "rate_limited",
  "message": "Retry after 2s"
}

Client guidance

On 401, re-run Connect / token mint — do not reuse expired JWTs.
On 403, check pack scopes and write consent with the operator.
On 429 / 503, exponential backoff; gate on /ready when load balancing.
Never log Authorization headers.

Next: Disclosure Boundary

Authentication