# Driftflight API errors: 402, bearer_required, insufficient_funds

This page lists the error codes Driftflight's storefront documents for image calls, credit purchases and top-ups, with the one recovery for each that cannot charge you twice. A 402 with a `payment` block and no `reason` is not an error but the price quote, $0.01 for a sketch image, which you pay and retry. Any other code is a message: match it below, and confirm the last payment's outcome before you make a new one.

## At a glance

- **Endpoint:** `POST https://agents.driftflight.com/zcj/ng0sasnyqv4i/v1/images/generate` with `prompt`, `model` (`sketch`, `studio` or `gallery`) and optional `preset`
- **Error shape:** JSON with the code in the top-level `error` field, sometimes refined by a `reason` or a human `detail` note
- **Price quote:** a 402 with a `payment` block and no `reason`. Pay it over x402 (Base USDC) or MPP (Tempo USDC), the wallet rails, and retry the same request.
- **When you're charged:** only when you pay a 402. An x402 exact payment is charged in full when you pay and is not returned if delivery fails.
- **Retry unchanged:** among the payment errors, only `payment_provider_unavailable`, with backoff. Every other payment code needs a change or a check first.
- **Reconcile before paying again:** the `zc-billing` header on the paid response, and `GET https://agents.driftflight.com/zcj/ng0sasnyqv4i/agent/entitlements` with your bearer credential for credit-funded calls
- **Full lists:** [error reference](https://agents.driftflight.com/zcj/ng0sasnyqv4i/errors.md) and the [buyer skill](https://agents.driftflight.com/zcj/ng0sasnyqv4i/SKILL.md) for the purchase flow

## The 402 price quote

Send the request with `model` set. The storefront bills a request without `model` as studio.

```bash
curl -i -X POST https://agents.driftflight.com/zcj/ng0sasnyqv4i/v1/images/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "a watercolor study of a harbour at low tide", "model": "sketch", "preset": "watercolor"}'
```

This example request returns a 402 in 0.3 seconds. The body carries `payment` with `id` and `amountUsd`, `plan`, `protocols` with an `x402` and an `mpp` entry, `accepts`, `terms` and `auth`, and no `reason`. The signable challenges arrive in the `payment-required` header for x402 and the `www-authenticate` header for MPP.

- **Means:** the normal per-call charge. Nothing is charged yet.
- **Do:** settle the challenge with your payment client and retry the same request with the proof attached.
- **Don't:** pay a 402 that carries a `reason`, and don't pay a fresh quote for a request whose earlier payment has an unknown outcome.

## Payment codes

### settlement_failed with insufficient_funds

Your signed payment did not settle. `settlementReason` says why, for example `insufficient_funds`. Fund the wallet, then send the request again from the start for a fresh challenge. Don't resend the old signed payment.

### payment_consumed

The payment was already settled and cannot be spent again. Check the original request's delivery first: its `zc-billing` header, or your entitlements for a credit-funded call. If you cannot establish the outcome, stop and report it as unknown. Don't request a new challenge or pay again because a response was lost.

### payment_refunded, payment_failed, payment_released

That payment reference is closed for good and can't be used again. Check what happened to the earlier request as for `payment_consumed`: its `zc-billing` header, or your entitlements for a credit-funded call. If the outcome can't be established, stop and report it as unknown. Don't repay a request because its response was lost.

### payment_incomplete

The payment you referenced has not finished. For a card payment, poll the `statusUrl` from the 402's `card` block until it reports complete, then retry with the same `zc-payment-id`. Don't start a second payment while the first is pending.

### payment_unknown

No payment available to you at this storefront has that reference. Confirm the id you sent. If it was taken from an old challenge, send the request again for a new 402.

### payment_provider_unavailable

A transient failure reaching the payment provider. Retry the request unchanged, with backoff. This is the only payment error where an unchanged retry is the recovery.

## Identity codes

A bearer credential is the agent identity the storefront issues. Pay-as-you-go calls don't need one. Plan purchases, top-ups and entitlement lookups do.

### bearer_required

Status 401. The call needs an agent identity, and a wallet payment cannot stand in for one. A plan purchase without a bearer returns this before any price is quoted, so nothing is charged. Reuse a stored credential, or register at [auth.md](https://agents.driftflight.com/zcj/ng0sasnyqv4i/auth.md). Then retry with `Authorization: Bearer <token>`. On MPP, `Authorization` carries the payment, so send `ZC-Agent-Authorization: Bearer <token>`. Don't create a new identity when you already hold one.

### invalid_token

Status 401. The credential did not verify, and `reason` says why:

| `reason` | Action |
| --- | --- |
| `token_expired`, `token_invalid` | Exchange your stored assertion at `/oauth2/token` for a fresh token |
| `malformed_agent_authorization` | Send exactly one `Bearer <token>` in `ZC-Agent-Authorization` |
| `unrecognized_agent_credential` | Put only a ZeroClick-issued token in that header |
| `conflicting_agent_credentials` | Send one agent token, not two |
| `combined_authorization_unsupported` | Move the token from a comma-combined `Authorization` to `ZC-Agent-Authorization` |

A 401 is not evidence that a purchase is absent. Don't buy again after one.

### identity_invalid

The storefront could not verify your identity proof. Sign a new challenge and send the request again.

## Plan and credit codes

### plan_required

Status 403. Either your plan doesn't cover a meter this call uses (`reason` is `not_included_in_plan`, and `meters` lists them), or you have no plan and the call carries no per-request price (`reason` is `access_not_found`). The body's `plans` lists the plans that cover the call, each with its `purchase.url`. Check your entitlements, then buy one with your bearer and retry.

### access_not_found

Make sure you are presenting the right identity, then look for existing and pending purchases with `GET /agent/entitlements` before you buy with `POST /plans/{planId}/purchase`. The plan's address is its `purchase.url` in [manifest.json](https://agents.driftflight.com/zcj/ng0sasnyqv4i/manifest.json).

### usage_exhausted

The plan's credit ran out. Top up with `POST /extend`, your bearer and `{"amountUsd": "<whole-cent amount>"}`, at least $1 for Prepaid credits, and pay the 402 it returns. The new balance comes back as `access.remainingCreditUsd`.

### entitlements_not_available

Status 501. The storefront returns this code when plan purchases or top-ups are not available. Pay-as-you-go per call still works.

## Bad request codes

Status 400. Fix the request, then send it again.

| Code | Meaning | Action |
| --- | --- | --- |
| `invalid_request` | The body is malformed | Fix the JSON |
| `payg_not_purchasable` | You tried to buy Pay as you go | Call the API instead |
| `amount_required` | A credit purchase without an amount | Include `amountUsd` |
| `amount_not_cent_increment` | `amountUsd` is not whole cents | Round to whole cents |
| `amount_below_minimum` | Under the plan's `purchase.minimumUsd`, $1 for Prepaid credits | Send at least the minimum |
| `amount_above_maximum` | Over the plan's `purchase.maximumUsd` | Buy up to it now, top up later |
| `amount_below_card_minimum` | Under the card floor of $0.50 | Send at least `purchase.cardMinimumUsd`, $1 for Prepaid credits, or pay on a wallet rail |

## Not found codes

Status 404.

| Code | Meaning | Action |
| --- | --- | --- |
| `seller_not_found` | The host does not map to a seller | Send requests to `https://agents.driftflight.com/zcj/ng0sasnyqv4i` |
| `plan_not_found` | Unknown plan id | Use an id from [manifest.json](https://agents.driftflight.com/zcj/ng0sasnyqv4i/manifest.json) |

## Seller and configuration codes

Status 409. These are not caused by your request.

| Code | Meaning | Action |
| --- | --- | --- |
| `signing_secret_required` | The seller has not finished setup | Retry later |
| `usage_not_priced` | The call's usage is at a rate the storefront has no price for, so it could not be billed | Retry later |
| `payment_request_mismatch` | A payment was reused for a different request | Request a fresh 402 and settle that one |
| `payment_amount_mismatch` | A purchase or top-up retry carried a different `amountUsd` than the paid challenge | Retry with the amount the 402 quoted |

### zc-usage-error header

A successful response can carry `zc-usage-error`, for example `invalid_usage_header`, when the usage report could not be billed. You were served the response. Don't retry it. Once a paid call is proxied, any other error body is Driftflight's own API status and body.

## Frequently asked questions

### I got a 402 after paying. Should I pay again?

Not until you reconcile. If the 402 carries a `reason` or an `error` code from this page, it is a message: act on that entry. If it is a plain price quote, first confirm what happened to the earlier payment from its `zc-billing` header or your entitlements. If the outcome cannot be established, stop and report it as unknown rather than paying a second time.

### What does bearer_required mean?

The call needs an agent identity credential, which a wallet payment cannot supply. It appears on plan purchases and top-ups, before any price is quoted, so nothing has been charged. Register or reuse a credential at [auth.md](https://agents.driftflight.com/zcj/ng0sasnyqv4i/auth.md) and retry with `Authorization: Bearer <token>`, or `ZC-Agent-Authorization` on MPP.

### What does insufficient_funds mean on x402?

It is the `settlementReason` on a `settlement_failed` response: your signed payment did not settle because the wallet could not cover it. Fund the wallet and send the request again from the start, so the storefront issues a fresh challenge. Don't reuse the old signed payment.

### Which errors are safe to retry unchanged?

Among the payment errors, only `payment_provider_unavailable`, with backoff. Seller and configuration codes call for a retry later. Every other payment code needs a fresh challenge or a reconciliation of the last payment before anything is sent again.

## Keep reading

- [Error reference](https://agents.driftflight.com/zcj/ng0sasnyqv4i/errors.md): the storefront's error codes and how to react
- [Buyer skill](https://agents.driftflight.com/zcj/ng0sasnyqv4i/SKILL.md): the full purchase and recovery flow
- [How to pay](https://agents.driftflight.com/zcj/ng0sasnyqv4i/payment.md): rails, plans, top-ups and `zc-billing`
- [Identity](https://agents.driftflight.com/zcj/ng0sasnyqv4i/auth.md): register, exchange and refresh a bearer credential
- [Card payments](https://agents.driftflight.com/zcj/ng0sasnyqv4i/payment/card.md): checkout and the `statusUrl`

---

Updated 2026-10-08. All Driftflight guides: https://agents.driftflight.com/guides.md. Storefront: https://agents.driftflight.com/zcj/ng0sasnyqv4i/llms.txt.