Errors and retries

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.

Getting started

Concepts

About

Errors and retries