> ## Documentation Index
> Fetch the complete documentation index at: https://docs.planewallet.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Decide whether to correct a request, wait, or reconcile an uncertain result.

## Read both HTTP status and the error body

Errors may use `{ "statusCode": 403, "message": "SCOPE_REQUIRED" }` or a validation body with a `code` and explanatory `message`. Preserve the operation ID and your idempotency key in your logs; never log credentials or card details.

| Code                              | Meaning                                       | Next action                                   |
| --------------------------------- | --------------------------------------------- | --------------------------------------------- |
| `INVALID_KEY`                     | Key is missing, invalid, or revoked           | Check credentials and environment             |
| `SCOPE_REQUIRED`                  | Key lacks a required permission               | Issue an appropriately scoped key             |
| `VERIFICATION_REQUIRED`           | Live or API access is not approved            | Complete individual or corporate verification |
| `LIVE_INTEGRATION_NOT_ENABLED`    | Live capability is unavailable                | Contact support; do not retry purchases       |
| `VALIDATION_ERROR`                | Request fields are invalid                    | Correct the request                           |
| `PRODUCT_NOT_FOUND`               | Product is unavailable in this environment    | Refresh the catalog                           |
| `BELOW_MINIMUM` / `ABOVE_MAXIMUM` | Amount is outside product limits              | Use the published product limits              |
| `VERIFIED_HOLDER_REQUIRED`        | Holder is not eligible for issuance           | Resolve holder verification                   |
| `INSUFFICIENT_BALANCE`            | Available balance is too low                  | Fund the company account                      |
| `QUOTE_CHANGED`                   | Expected total differs from the current quote | Re-quote and confirm the new price            |
| `IDEMPOTENCY_CONFLICT`            | Key was reused with different data            | Retrieve the original operation               |
| `INVALID_CURSOR`                  | Pagination cursor is invalid                  | Use the returned cursor unchanged             |
| `RATE_LIMITED`                    | Request budget exceeded                       | Back off with jitter                          |

## Transport errors

After a timeout or connection failure on `POST /operations`, retry the exact request using the original idempotency key. Do not create a new order identifier to escape an error.

Use bounded exponential backoff with jitter for transient read errors. Stop on a persistent 4xx error and correct the cause. An operation in `manual_review` retains an unresolved outcome and may retain its reserve; contact support with the operation ID.

## Verification and card-account errors

| Code                         | Action                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `MONTHLY_CARD_LIMIT_REACHED` | Individual issuance is limited to 500 per UTC calendar month; pending requests count. |
| `WHOLE_USD_REQUIRED`         | Request a whole USD invoice amount, at least 10 USD.                                  |
| `BELOW_PROVIDER_MINIMUM`     | Use the current `minimum` returned in the error response.                             |
| `FUNDING_INVOICE_PENDING`    | Retrieve the existing invoice before creating another.                                |
| `INVOICE_RESULT_UNKNOWN`     | Do not retry creation or pay a new invoice. Contact support for reconciliation.       |
| `USE_CARD_ACCOUNT_INVOICE`   | Replace the retired funding-address endpoint with card-account invoices.              |
| `STATEMENT_RANGE_TOO_LARGE`  | Shorten the date range; a statement can contain up to 10,000 ledger entries.          |