Errors
Every error is a JSON envelope with a stable machine-readable code, a human-readable message, and links back to its own documentation and request log. The doc_url on any error response points to an anchor on this page.
The envelope
{
"error": {
"type": "invalid_request_error",
"code": "invalid_request",
"message": "amount must be a positive integer string (base units)",
"param": "amount",
"doc_url": "https://…/docs/errors#invalid_request",
"request_log_url": "https://…/v1/request-logs/rql_01J…",
"request_id": "req_01J…"
}
}type is one of api_error, invalid_request_error, authentication_error, idempotency_error, rate_limit_error. code is the stable value to branch on — codes are never renamed.
Error codes
invalid_request HTTP 400
A parameter is missing, malformed, or inconsistent. The param field names the offending parameter when one is identifiable.
invalid_state HTTP 400
The resource exists but is not in a state where this operation is allowed — for example refunding a payment that never captured. State machines are closed sets; the message names the current state.
authentication_required HTTP 401
No API key was provided, or the key is unknown, rolled, or deactivated. Provide your secret key as a Bearer token.
insufficient_scope HTTP 403
The API key is valid but lacks the scope this endpoint requires (for example checkout:write). Mint a key with the right scopes in the dashboard.
resource_missing HTTP 404
No resource with that id is visible to your merchant in this mode. Test and live data never cross: a test-mode key cannot see live objects, and vice versa.
session_not_open HTTP 409
The checkout session has moved past open (already submitting, completed, or expired). Mint a fresh session instead of retrying this one.
idempotency_key_in_use HTTP 409
A request with the same Idempotency-Key is currently in flight. Wait for it to finish and retry — the stored response will be replayed.
idempotency_error HTTP 409
The Idempotency-Key was previously used with a different request body. Keys pin exact payloads; use a new key for a new request.
compliance_blocked HTTP 400
The requested combination is not permitted by the compliance rules layer — for example a non-MiCA-authorized stablecoin for an EEA session. Merchant configuration cannot override this.
rate_limited HTTP 429
Too many requests. Back off and retry with jitter; the response includes standard rate-limit headers.
internal_error HTTP 500
Something failed on our side. The request_id (also in the request-id response header) lets support trace the exact request — include it when you write in.
Payment declines
Declines are not HTTP errors — a declined attempt is a successful API call whose payment object carries the outcome. Look at the attempt's error_code (for example card_declined, insufficient_funds) and error_category (such as issuer_decline or technical) rather than catching exceptions.