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

# Errors and retries

> Interpret Ledger errors and choose safe retry behavior.

Ledger returns JSON with an `error` code and an HTTP status. Validation failures may also include `issues` with field paths.

| Status | Meaning | Action |
| - | - | - |
| `400` | Invalid body, ID, or unsupported request | Correct the request before retrying. |
| `401` | Missing or invalid API key | Check the server-side key or rotate it in the dashboard. |
| `404` | Customer, feature, plan, or add-on is missing | Confirm the ID and organization. |
| `409` | Duplicate item, insufficient credits, conflicting request ID, or pending Checkout | Inspect `error` and the current state before retrying. |
| `502` | Stripe Checkout is unavailable | Retry the same attach request after Stripe recovers. |
| `503` | Live charges are gated or a payment dependency needs retry | If `live_charges_disabled`, finish live activation and wait for Ledger's deployment gate. For transient payment failures, retry the same intended action. |

Use a stable `requestId` for each successful feature action. Retrying `/v1/track` with the same customer, feature, and request ID returns `idempotent: true`; reusing that ID for another feature returns `request_id_conflict`. For plan upgrades, generate one `Idempotency-Key` per intended upgrade and reuse it only for retries of that upgrade.

A paid plan can be created before Stripe is connected. The item remains durable and `stripeSync: awaiting_connection` indicates that a later Stripe connection must sync it. If sync fails, inspect the plan's `stripeSyncStatus` and retry after fixing the Stripe connection.

`409 live_not_ready` on dashboard activation includes a `missing` list: `api_key`, `stripe_connection`, `webhook`, `checkout_urls`, or `catalog_sync`. Complete those setup steps in Live and try activation again. `400 environment_mismatch` on whole-catalog publishing means the body environment does not match the API key. See [Sandbox and live environments](https://docs.integrateledger.com/environments.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.