payment_required (402)

← Error reference

payment_required

HTTP status: 402

Retryable: No — retrying without changes will fail the same way.

The org is entitled but cannot spend: its wallet is inactive or it has no credits.

When it fires

A request hit a billing-gated endpoint while the org is entitled (active subscription, or trial within its window) but cannot pay — the wallet is `locked`/`closed`, or the spendable balance is below what the operation needs. The gate consults a cached billing-state snapshot maintained by the billing-worker (see the billing credit-wallet MVP design §2/§7).

How to handle it

Top up credits (or re-activate the wallet) from the console, then retry. The cache refreshes within seconds of a successful top-up. Retrying without adding credits will produce the same response.

Example response

{
  "error": {
    "type": "https://docs-dev.autohost-dev.uk/api/errors/payment_required",
    "code": "payment_required",
    "message": "Insufficient credits. Top up to continue.",
    "request_id": "req_01HEXAMPLE0000000000000000",
    "doc_url": "https://docs-dev.autohost-dev.uk/api/errors/payment_required"
  }
}