Reference

Errors & Status Codes

Every non-2xx response uses the same body shape: a single error string meant to be read by a developer. There is no numeric error code or structured field to switch on — branch on the HTTP status and, for a payment, on its status value.

JSON

{ "error": "human-readable message" }

HTTP status codes#

The API uses a small, conventional set of status codes.

Status	Meaning
`400 Bad Request`	Malformed or invalid request: bad JSON, a missing or invalid field, or a request that isn't valid for the current state of the resource.
`401 Unauthorized`	Missing, malformed, or invalid credentials — a bad `sk_` API key, a wrong `cs_` client secret, or an invalid webhook signature.
`404 Not Found`	The resource does not exist, or is not visible to the authenticated account (a payment under another account, an unknown deposit index, an unknown seller).
`409 Conflict`	The request conflicts with the resource's current state — e.g. selecting a token after the asset is already fixed, or acting on an intent that has moved past that step.
`429 Too Many Requests`	Rate limited. Back off and retry after a short delay.
`500 Internal Server Error`	An unexpected server-side error. Safe to retry idempotent reads.
`502 Bad Gateway`	An upstream dependency failed — most often the price feed while converting the USD price to a token amount. Retry.
`503 Service Unavailable`	A dependency is temporarily unavailable (e.g. the price feed, or subscription charging paused). Retry after a short delay.

The body is always { "error": "..." }. The error string is for logs and developers; do not parse it or match on its exact wording, since messages can change.

Common errors by endpoint#

The messages below are representative of what each surface returns. Match on the status code, not the string.

`POST /intents`#

Status	Cause
`400`	Missing or non-positive `amount_usd_cents`, an empty or malformed `accepted_tokens`, or an invalid mint address.
`401`	Missing or invalid `sk_` API key.

Checkout SDK (client_secret endpoints)#

Status	Cause
`401`	Invalid or unknown `client_secret` — it doesn't match any live intent.
`409`	The amount is already fixed. Calling `select-token` again after an asset has been locked conflicts with the intent's state.
`400`	The requested asset is not in the intent's accepted tokens, or the intent has expired.
`502 / 503`	The price feed couldn't be reached to convert the USD price to a token amount. Have the client retry token selection.

Marketplace#

Status	Cause
`404`	The seller (identified by the on-behalf-of header) is unknown or not linked to the authenticated marketplace.
`400`	The `marketplace_fee_bps` exceeds the platform maximum reported at `GET /config`.
`429`	Too many requests across the marketplace's sellers. Back off and retry.

Subscriptions#

Status	Cause
`404`	The subscription or plan does not exist under the authenticated account.
`409`	The subscription isn't in a state that allows the requested action (e.g. cancelling one already cancelled).
`503`	Subscription charging is temporarily paused / a dependency is unavailable. Retry after a short delay.

Payment status values#

A payment's status is the field to branch on — it's stable and enumerable, unlike the message string. Each value maps to a concrete action on your side. See the Payment lifecycle for how they transition.

Status	Your action	Meaning
pending	Wait / show the deposit address.	Intent created; no funds received yet.
underpaid	Await the remainder, or refund.	Received less than the expected amount.
paid	Fulfill the order.	Received the expected amount; settlement is in progress.
overpaid	Fulfill; the excess is refunded automatically.	Received more than the expected amount.
settling	Wait.	Funds are being swept to your treasury wallet.
swept	Record revenue from `settlement`.	Settled to your wallet; the exact amounts are final.
refunding	Await refund completion.	A balance is being returned to the payer.
refunded	Treat the order as reversed.	A refund has completed.
cancelled	Release inventory.	Nothing received — timed out, or explicitly cancelled with no funds.
settle_failed	Alert ops / reconcile manually.	Automatic settlement exhausted its retries.
refund_failed	Alert ops / reconcile manually.	Automatic refund exhausted its retries.

Drive fulfillment from webhooks and branch on type plus the status in the body, never on arrival order. See Webhooks.