Errors & problem+json

Every non-2xx from the Management API is application/problem+json (RFC 9457) with a registered type, a stable machine-readable code, and a request_id that matches the TT-Request-Id header carried on every response.

For symptom-first fixes keyed to what you’d actually search — 401 storms, UNPRICED rows, silent routing — see Troubleshooting.

The envelope

• type — a relative on-host path (air-gap-dereferenceable), documented at /tt/api/problems/<slug>; the full registry is served at /tt/api/v1/problems.
• code — a stable string code.
• request_id — matches the TT-Request-Id response header, for correlation with the ledger and the audit trail.

Framework problems

These apply to every operation and are documented once (they’re each operation’s default response):

Status	Problem
400	bad_request
401	unauthenticated
403	forbidden (names the required_scope in the body and the TT-Required-Scope header)
404	not_found
405	method_not_allowed
413	payload_too_large
429	rate_limited (with Retry-After)
500	internal

Special status codes worth knowing

• 412 precondition_failed — a config compare-and-swap lost the race; refetch the generation and retry (If-Match).
• 422 restart_required — a restart-only config change (e.g. a webhooks: edit) was submitted; nothing was written (previews still return 200). Also 422 unsupported_override_class when overriding a rate/concurrency limit per node.
• 410 gone — a sunset operation (names its successor), or 410 cursor_expired on the events feed (carries oldest_seq so you can reconcile from the audit trail).
• 503 enforcement_unavailable — a fail: closed governance limit whose guarantee is uncheckable (never a fake 429; see Governance).

Governance refusal reasons

Governance refusals map a reason to a status: invalid_key → 401, scope_violation → 403, budget_exceeded / quota_exhausted / rate_limited / concurrency_exceeded → 429, enforcement_unavailable → 503. Each is written row == wire — the HTTP response and the decision-log row are stamped from the same value.

The full catalog, and the type registry, are in the rendered API reference.