payment_required (402)

← Error reference

payment_required

HTTP status: 402

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

The wallet cannot cover the operation: insufficient balance, or a locked/closed wallet.

When it fires

A request hit a billing-gated endpoint and the wallet is not spendable for the amount — the spendable balance (in USD) is below what the operation needs, the wallet is `locked`/`closed` (for example, frozen by a card dispute), or there is no wallet at all. Access is balance-first: a positive balance from any source (trial, subscription grant, or prepaid top-up) is enough; no subscription is required to spend funds. The gate consults a cached billing-state snapshot maintained by the billing-worker (see the PLG two-bucket billing design §3/§8).

How to handle it

Add funds with a top-up from the console, then retry — the cache refreshes within seconds of a successful top-up. If the wallet is `locked` or `closed`, contact support to release it after review. Retrying without adding funds will produce the same response.

Example response

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