payment_required (402)
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: apart from the ID scan API (below), a positive balance from any source (trial, subscription grant, or prepaid top-up) admits a request, and 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). The ID scan API (POST /v1/id-verification) also checks the price: when the balance cannot cover one scan, the call is refused with this code before the document is read.
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. The retry can reuse its Idempotency-Key, because this refusal is never stored as the result for that key. 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 credits. Top up to continue.",
"request_id": "req_01HEXAMPLE0000000000000000",
"doc_url": "https://docs-dev.autohost-dev.uk/api/errors/payment_required"
}
}