Errors

Public error categories for Cleared REST. Stable enough to branch on; not a dump of internal exceptions.

Maturity: Contract-preview. HTTP status + code pairs below are the vocabulary to implement against.

Categories

HTTP	`code`	Meaning for integrators
400	`invalid_request`	Schema / validation failure
401	`unauthorized`	Missing, malformed, or revoked key
403	`forbidden`	Authenticated but scope or actor boundary blocks
404	`not_found`	Resource not visible in scope (no existence oracle beyond this)
409	`conflict`	Idempotency or state conflict
422	`gate_denied`	Gate refuses action (business deny)
429	`rate_limited`	Back off and retry with jitter
503	`unavailable`	Temporary; gate callers must deny while unhealthy

Do not parse internal detail strings as contract. Prefer code + HTTP status.

Envelope

Synthetic:

{
 "error": {
 "code": "gate_denied",
 "message": "No live eligibility pass for requested action.",
 "reason_code": "no_live_pass",
 "request_id": "req_synth_001"
 }
}

Examples

Unauthorized

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "error": {
 "code": "unauthorized",
 "message": "Invalid API key.",
 "request_id": "req_synth_002"
 }
}

Gate denied

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
 "error": {
 "code": "gate_denied",
 "message": "Eligibility check denied.",
 "reason_code": "expired",
 "request_id": "req_synth_003"
 }
}

Some environments return 200 with allowed: false for gate; others use 422 + gate_denied. Your issued OpenAPI pins one. In both cases the business action must not proceed.

Replay of the same Idempotency-Key on create/seal returns the original success body (or a conflict if the key was reused with a different body). Safe to retry create/seal on network failure with the same key.