# Pizza Ex Machina API errors and recovery: codes and fixes

This reference lists every error you meet when you buy on the Pizza Ex Machina storefront or call its seller API, with one meaning and one action for each. You fix most of them by reading, not paying: the receipt names your account, you redeem a lost key again from that account, and you top up an empty balance on it from $0.50. Buying a second account is never the fix.

## At a glance

- **Two credentials:** The buyer bearer goes to `https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi` for purchases, receipts, key redemption and top-ups. The `pxm_live_` key goes to `https://api.pizzaexmachina.com` as `Authorization: Bearer pxm_live_...`. Never send the bearer to the seller API.
- **Error shape:** JSON with the code in `error`. Storefront errors can add `reason`, `hint` or `detail`. Seller API errors add a `detail` that names the problem.
- **Recovery order:** Read the receipt, then redeem a fresh key from the selected account, then top up that account.
- **Receipt:** `GET https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/purchases/receipt` with the bearer lists each account with its `accessId`, `provisioningState`, `redeemUrl` and `topUpUrl`.
- **Out of credit:** The seller API's only 402 is `insufficient_credit`. Top up the same account. The key keeps working.
- **Amounts:** A Credits purchase or top-up takes a whole-cent `amountUsd` of at least $0.50. By card the minimum is $0.50.
- **Not billed:** `502 run_failed` is not billed, and creating or listing agents is free. A run costs $0.01 per run plus its oven's token rates.
- **Full flow:** [the buyer skill](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/SKILL.md) and [the error reference](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/errors.md).

## Storefront errors when buying or recovering access

These errors come from the storefront on a plan purchase, a top-up, a receipt read or a key redemption. A 402 is the storefront's price quote. You pay it over x402 or MPP, the wallet rails that settle in USDC, or by card, and then retry the same request.

| Code | Status | Meaning | Action |
| --- | --- | --- | --- |
| `bearer_required` | 401 | The purchase or top-up carried no agent credential. No price was quoted. | Reuse a stored credential, or register at [auth.md](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/auth.md). Retry with `Authorization: Bearer <token>`. On MPP, send `ZC-Agent-Authorization: Bearer <token>` instead. |
| `invalid_token` | 401 | The bearer did not verify. `reason` says why. | For `token_expired` or `token_invalid`, exchange the stored assertion at `/oauth2/token` for a fresh token and retry. This 401 does not mean you own nothing. |
| `verified_email_required` | 403 | The plan needs a credential that a human has claimed with a verified email. The Free trial is one such plan. | Complete the claim step in auth.md, exchange again, then retry the same action. Without the claim, every retry fails. |
| `amount_required` | 400 | A Credits purchase arrived without `amountUsd`. | Add `amountUsd` as a decimal string of at least $0.50. |
| `amount_below_minimum` | 400 | `amountUsd` is under the plan's `purchase.minimumUsd`. | Send at least $0.50. |
| `amount_not_cent_increment` | 400 | `amountUsd` is not a whole-cent value. | Round to whole cents. |
| `amount_below_card_minimum` | 400 | The amount cleared the plan minimum but not the card minimum. | By card, send at least $0.50 (`purchase.cardMinimumUsd`). Or pay on a wallet rail, which needs only the plan minimum. |
| `free_plan_already_claimed` | 409 | Your human already holds the Free trial, through this agent or another one. The body returns the existing `accessId`. | Redeem a key for that `accessId`. |
| `provisioning` | 503 | The account is still being set up. `retryAfterSeconds` is the wait. | Wait that many seconds, read the receipt, then retry the redemption. Do not repeat the purchase. |
| `access_provisioning_failed` | 409 | Pizza Ex Machina could not create the account. `moneyOutcome` says what happened to the payment. | `refunded` or `released` means the money was returned. `reconciliation_required` means settlement is being corrected. Report it and stop retrying. |
| `key_mint_failed` | 502 | The redemption could not mint a key. | Read `reason` and report it. Do not redeem or purchase again in a loop. |

Match these codes by the `error` field:

| Code | Meaning | Action |
| --- | --- | --- |
| `settlement_failed` | The signed payment did not settle. `settlementReason` says why, for example `insufficient_funds`. | Fix the wallet, then send the request again from the start to get a fresh 402. |
| `payment_consumed` | That payment has already settled and cannot be spent again. | Read the receipt to confirm the original purchase was delivered before you request a new 402. |
| `access_not_found` | The storefront could not match an account to your identity or selection. | Recheck the identity and the `accessId` you selected from the receipt. |

A Credits purchase sent without a bearer gets this answer before any price is quoted. This example took 0.1 seconds. The example below omits the body's `auth` block, which points to the identity recipe:

```json
{"error":"bearer_required","hint":"Purchases require the agent access token. Register once, exchange the assertion for a token, and retry with Authorization: Bearer <token> (or ZC-Agent-Authorization: Bearer <token> when Authorization carries your MPP Payment credential)."}
```

## Seller API errors when creating or running agents

These errors come from `https://api.pizzaexmachina.com` when you call it with the `pxm_live_` key. Each body carries `error` and a `detail`.

| Status | Code | Meaning | Action |
| --- | --- | --- | --- |
| 401 | `unauthorized` | No Bearer token was sent. | Send the key as `Authorization: Bearer pxm_live_...`. If you hold no key, follow the recovery order below. |
| 401 | `invalid_api_key` | The key is unknown or revoked. A redemption with `maxKeys` of `1` replaces the old key, and generating a key at pizzaexmachina.com revokes the previous one. | Use the newest key. If you hold none, redeem a fresh one from the same account. |
| 402 | `insufficient_credit` | The prepaid balance cannot cover the run fee. The body carries `remainingCreditUsd`. | Top up the same account, then retry the run. The key stays the same. |
| 403 | `account_suspended` | The account is suspended. | Contact Pizza Ex Machina billing and stop retrying. |
| 404 | `agent_not_found` | No agent with that id exists on this account. | `GET /v1/agents` with the same key lists this account's agents. |
| 400 | `invalid_request` | A field is missing or malformed. `detail` names it. | Fix that field and send the request again. |
| 502 | `run_failed` | The backend that runs the model was down. Nothing is billed for this run. | No billing action is needed. |

A run sent with no key gets `401` with `"error": "unauthorized"`, and its `detail` says a `pxm_live_` key is required and that you get one by buying prepaid credit on the storefront. This example took 0.1 seconds.

A run against an id the account does not have gets this 404. This example took 0.5 seconds:

```json
{"error":"agent_not_found","detail":"No such agent on this account."}
```

The following create request omits `instructions`:

```bash
curl -X POST https://api.pizzaexmachina.com/v1/agents \
  -H "Authorization: Bearer pxm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Empty", "model": "forno-1"}'
```

It gets this 400. This example took 0.2 seconds:

```json
{"error":"invalid_request","detail":"instructions is required"}
```

To fix it, add `instructions` and send the request again. Instructions and run input are each limited to 4,000 characters.

## Lost API key recovery and top-up on the same account

1. **Read the receipt.** Send `GET https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/purchases/receipt` with `Authorization: Bearer <token>`. A 200 returns a `purchases` array. Each entry carries `accessId`, `plan`, `access`, `provisioningState`, `delivery`, `redeemUrl` and `topUpUrl`. Select the account for the plan you intend to use. If the bearer gets a 401, exchange it again and read the receipt again before you draw any conclusion.
2. **Wait for provisioning.** Redeem only when `provisioningState` is `active` and `delivery.status` is `active`.
3. **Redeem a fresh key.** POST the account's `redeemUrl` (`https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/keys/redeem`) with the bearer and a JSON body holding that `accessId`. The body needs the `accessId` when you hold more than one account. A 200 returns `accessId`, `apiKey`, `maxKeys` and `keyExpiresAt`. The key is shown once, so store it immediately. If the purchase carried your human's verified email, your human can instead sign in at [pizzaexmachina.com](https://pizzaexmachina.com) and generate a new key. That revokes the previous key.
4. **Top up the same account.** POST the account's `topUpUrl` with the bearer and an `amountUsd` of at least $0.50. You can also send `POST https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/extend` with the `accessId`. Pay the 402. On MPP, the bearer moves to `ZC-Agent-Authorization`. Success returns `extended=true` and `access`, and the existing key keeps working.
5. **Buy only when the receipt shows no eligible account.** Send `POST https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/plans/{planId}/purchase` with the bearer. The Credits plan's `purchase.url` is in [manifest.json](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/manifest.json). The [buyer skill](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/SKILL.md) covers the full purchase flow.

## Frequently asked questions

### I lost my pxm_live_ key. How do I recover it?

Read the receipt with your bearer, select the account, and POST its `redeemUrl` to mint a fresh key for that same account. With `maxKeys` of `1`, the new key replaces the old one. If the purchase carried your human's verified email, your human can also generate a new key at pizzaexmachina.com, which revokes the previous key.

### How do I top up after a 402 insufficient_credit?

POST the account's `topUpUrl` from the receipt with your bearer and an `amountUsd` of at least $0.50 ($0.50 by card), then pay the 402. The credit goes to the same account, so the key you already hold keeps working and you can retry the run.

### Why does a key I just used return 401 invalid_api_key?

The key is unknown or revoked. Redeeming again with `maxKeys` of `1`, or generating a key at pizzaexmachina.com, replaces the previous key. Switch every caller to the newest key. If none is stored, redeem one from the same account.

### Does the buyer bearer work at the seller API?

No. The bearer is for storefront purchases, the receipt, key redemption and top-ups. Calls to `https://api.pizzaexmachina.com` take only the `pxm_live_` key as `Authorization: Bearer`.

### Is a failed run billed?

No. `502 run_failed` means the backend that runs the model was down, and nothing is billed for that run.

## Keep reading

- [Buyer skill](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/SKILL.md): the full purchase and recovery flow
- [Standing accounts](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/accounts.md): provisioning, key redemption, top-ups and recovery
- [Error reference](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/errors.md): every storefront error code
- [Identity](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/auth.md): register, claim and exchange a bearer credential
- [How to pay](https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/payment.md): rails, plans and minimums
- [Pizza Ex Machina API reference](https://pizzaexmachina.com/docs): endpoints, limits and seller API errors

---

Updated 2026-10-12. All Pizza Ex Machina guides: https://agents.pizzaexmachina.com/guides.md. Storefront: https://agents.pizzaexmachina.com/zcj/6uwos88pg9mi/llms.txt.