payment_required (402)

View as Markdown Open in ChatGPT Open in Claude

`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.checktiv.com/api/errors/payment_required",
    "code": "payment_required",
    "message": "Insufficient credits. Top up to continue.",
    "request_id": "req_01HEXAMPLE0000000000000000",
    "doc_url": "https://docs.checktiv.com/api/errors/payment_required"
  }
}