Errors

Integrator appendix. Stable public categories so clients can handle failure without guessing.

Examples 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 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	Schema validation failed. Fix args from the tool schema
Upstream / peer unavailable	`502` / `503`	Shared-record peer path unavailable. Retry later
Internal	`500`	Unexpected failure. Retry with backoff. Contact operator if persistent

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.
Never log Authorization headers.

Production Checklist

Infrastructure review