billing_unavailable (503)

← Error reference

billing_unavailable

HTTP status: 503

Retryable: Yes — the request did not change server state.

The billing-state cache could not be read; the request was refused to avoid silently bypassing quota.

When it fires

The quota gate read a billing-state snapshot from KV but the payload failed schema validation. We treat a corrupt snapshot as fail-closed (rather than fail-open) so a poisoned record cannot serve unbounded traffic. Genuine KV unavailability — i.e. no record at all — is also fail-closed but produces a 403 `subscription_required` (plus a background rebuild), not this code.

How to handle it

Retry with exponential backoff. The billing-worker overwrites the snapshot on its next refresh tick (sub-minute) and the gate succeeds again. Persistent occurrences are an internal incident — open a support ticket with the `request_id` rather than masking the response.

Example response

{
  "error": {
    "type": "https://docs-dev.autohost-dev.uk/api/errors/billing_unavailable",
    "code": "billing_unavailable",
    "message": "Billing state unavailable",
    "request_id": "req_01HEXAMPLE0000000000000000",
    "doc_url": "https://docs-dev.autohost-dev.uk/api/errors/billing_unavailable"
  }
}