API errors - Hosted checkout

This page is the single source for every error the Checkout API — POST /api/v1/checkout/sessions, GET /api/v1/checkout/sessions/{id}, and the cancel endpoint — can return. A card decline is not an error on this API — it’s a normal 201/200 response with a failed session status. See Payment outcomes for that path.

Problem format

The Checkout API returns errors as RFC 9457 application/problem+json bodies:

{
  "type": "urn:radiumone:checkout:session-invalid-state",
  "title": "RadiumOne error",
  "status": 409,
  "detail": "Session chk_3f9a1c2e5b7d4a608e1f2c3b4d5e6f70 is completed, expected pending",
  "instance": "/api/v1/checkout/sessions/chk_3f9a1c2e5b7d4a608e1f2c3b4d5e6f70/cancel",
  "code": "session:invalid_state",
  "details": { },
  "error": { "code": "session:invalid_state", "message": "Session chk_3f9a1c2e5b7d4a608e1f2c3b4d5e6f70 is completed, expected pending" }
}

TL;DR: Branch on code or type (they carry the same information) — never on title or detail. Every entry below is grouped by cause, with a stable anchor, HTTP status, retry rule, and — for 429 — the rate-limit body field.

code is the stable dotted identifier (for example session:invalid_state) — the value the tables below list, and the value error.code mirrors.
type is a derived tag URI: urn:radiumone:checkout: followed by code with every : and _ replaced by - (so session:invalid_state → urn:radiumone:checkout:session-invalid-state). A handful of codes are already full URNs from a different domain (for example urn:radiumone:auth:outlet-binding-violation) — code and type are identical for those. The one exception in the other direction is the catch-all 500 (internal:server_error): its type is the generic about:blank, not a derived URN.
title is a short label, not a stable identifier — many error paths share the generic title "RadiumOne error". Don’t branch on it.
detail is human-readable and can change, and may echo part of your request (for example the offending URL) — don’t parse it.
details carries typed extras for some errors, for example retry_after (seconds) on a 429.
error is a deprecated {code, message} mirror of code/detail, kept for backward compatibility. Prefer the top-level fields.

Authentication and authorization

Missing, malformed, or mismatched credentials on any of the three operations.

Code	HTTP	Cause	What to do	Retry?
`urn:radiumone:checkout:wrong-key-type`	400	A publishable key (`r1pk_…`) was used where a secret key is required	Use your secret key (`r1sk_…`) server-side; never call create/cancel from the browser	No
`urn:radiumone:checkout:missing-credentials`	401	`X-Api-Key` header is missing on create	Add the header	No
`security:unauthorized`	401	`X-Api-Key` header is missing on the cancel endpoint — a different code from create’s missing-header case	Add the header	No
`urn:radiumone:checkout:invalid-credentials`	401	`X-Api-Key` is malformed	Check the key value	No
`gateway:auth_failed`	401	Your key is well-formed but not recognized by the gateway	Confirm the key is active; contact support if it should be	No
`security:domain_not_allowed`	403	The `success_url`/`cancel_url` host (or, in embedded mode, your registered embedding domain) isn’t in your allowed domains	See Embedded checkout errors or register the host — Sandbox and API keys	No
`urn:radiumone:checkout:merchant-missing-publishable-key`	412	Your account has no active publishable key provisioned	Contact support to provision one	No
`outlet:binding_violation`	422	Your key is bound to a different outlet than the one requested	Omit `outlet_id`, or send the bound outlet	No

Validation

The request body failed a field rule or a cross-field check.

Code	HTTP	Cause	What to do	Retry?
`validation:invalid_input`	400	A field failed its rule (length, format, range) — including `success_url`/`cancel_url` that isn’t `https://` (or `http://localhost`) or doesn’t parse as a URL at all, or a `line_items` entry that’s `null`/not an object or has a non-string `name` — or the currency isn’t enabled for your merchant	Fix the field named in `detail`	No
`validation:line_items_mismatch`	400	`line_items`/`adjustments` don’t sum to `amount`	Fix the totals — see Customize checkout	No
`outlet:not_found`	422	The requested (or key-bound) outlet doesn’t resolve for your merchant. A malformed `outlet_id` (not a canonical UUID) instead returns `400 validation:invalid_input`	Check the outlet ID	No
`embed:origins_not_configured`	422	`mode: "embed"` was sent but no usable frame origin could be derived from your `allowed_domains` — an empty or unconfigured allow-list	Register at least one domain in `allowed_domains`, or use redirect mode — see Embed hosted checkout	No, until configured
`gateway:request_rejected`	422	The gateway rejected the create request as a business rule violation — for example an amount larger than the gateway allows	Fix the request per `detail`	No

Session state and idempotency

Session lookup, cancellation conflicts, and create-time idempotency. See Session lifecycle for the full state model behind these.

Code	HTTP	Cause	What to do	Retry?
`resource:not_found`	404	Malformed `checkout_id` or malformed key on GET/cancel	Check the ID/key	No
`session:not_found`	404	No session exists for that `checkout_id` on your account — never created, belongs to a different merchant (the two responses are byte-identical, on purpose), or past retention. Same on `GET` and cancel	Create a new session	No
`session:idempotency_conflict`	409	Two causes, same code: (1) a concurrent create raced for the same `order_reference` — `detail`: “A session for this order_reference is still being created; retry shortly”; (2) the `order_reference` matches a session that can still be paid (`pending` and not yet expired, `processing`, or `completed`) but with a different `amount` or `currency` — `detail`: “order_reference is already in use for a different amount or currency”. A replay with the same `order_reference`, `amount`, and `currency` returns the original session instead of either error — see Session lifecycle	Race: retry after a short delay. Amount/currency conflict: use a new `order_reference` for a genuinely different order, or resend the original amount and currency	Race: yes. Conflict: no — fix the request first
`session:invalid_state`	409	The operation doesn’t apply to the session’s current status — most commonly cancelling a session that isn’t `pending`	See Resolve checkout cancellation conflicts	GET first, then decide
`session_create_failed`	409	The session couldn’t be stored	Retry	Yes
`session_corrupt`	409	The stored session record couldn’t be read	Contact support	No

Configuration and availability

Your merchant configuration or the gateway itself is unreachable.

Code	HTTP	Cause	What to do	Retry?
`gateway:unavailable`	422	A protective circuit breaker is open for gateway reads (session create/verify)	See Handle payment service outages during checkout	Yes, after `retry_after_ms`
`urn:radiumone:checkout:merchant-context-unavailable`	503	Your merchant configuration couldn’t be loaded	Retry	Yes
`gateway:request_failed`	502	The gateway itself was unreachable or returned a server error while creating the session — no session was created	See Handle payment service outages during checkout	Yes

gateway:request_failed and gateway:unavailable both mean “no session was created, and it’s safe to retry the same create call” — they differ in cause (a genuine upstream failure vs. a breaker deliberately short-circuiting). Branch on code/type, not the HTTP status alone.

Rate limits and server errors

Code	HTTP	Cause	What to do	Retry?
`rate_limit:exceeded`	429	Too many requests	Wait `details.retry_after` seconds, then retry. The response also carries a `Retry-After` HTTP header with the same value in seconds — use either	Yes, after `details.retry_after` / `Retry-After`
`internal:server_error`	500	An unexpected server error	Retry, then contact support if it recurs	Yes

Next steps

Payment outcomes

Declines, expiry, and cancellation — not errors on this API.

Redirect and signature errors

Signature verification and return-URL signal reference.

Handle failures

Ten common failure scenarios, each with the exact signal and what to do.

Test your integration

Exercise these paths in sandbox before you go live.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

API errors - Hosted checkout

Problem format

Authentication and authorization

Validation

Session state and idempotency

Configuration and availability

Rate limits and server errors

Next steps

Payment outcomes

Redirect and signature errors

Handle failures

Test your integration

​Problem format

​Authentication and authorization

​Validation

​Session state and idempotency

​Configuration and availability

​Rate limits and server errors

​Next steps

Payment outcomes

Redirect and signature errors

Handle failures

Test your integration

Problem format

Authentication and authorization

Validation

Session state and idempotency

Configuration and availability

Rate limits and server errors

Next steps