Gateway HTTP errors

Status classes and codes

• 400 — invalid_json, invalid_operation_id, invalid_execute_request: malformed body or path; correct the request.
• 401/403 — authentication failure per auth mode; audit_replay_forbidden (missing audit.read scope); policy_rejected (policy decision was deny).
• 404 — operation_not_found, custody_key_not_found.
• 409 — operation_not_executed (publish before execute), result_ref_mismatch (expected_result_ref differs from the executed result), publication_receipt_mismatch (external export against a different receipt). Conflicts are state errors: re-read the view and follow next_actions.
• 429 — policy_admission_rate_limited: the admission token bucket is exhausted; retry with backoff and inspect gateway intake pressure.
• 500/502 — runtime or Policy Authority communication failure; the operation state is re-readable and idempotency keys make resubmission safe.

Retry discipline

Submissions are idempotent by key: after a network failure, resubmit with the same idempotency_key and compare the returned operation_id. Approvals are idempotent per subject. execute and publish are replay-safe per operation: a completed step returns the committed result. 4xx other than 429 indicates a request or state error that retries will repeat verbatim.