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 9457application/problem+json bodies:
TL;DR: Match the whole
type — never a prefix, and never the text after the last :. Don’t branch on title, detail, or the HTTP status alone. Every entry below is grouped by cause, with a stable anchor, HTTP status, and retry rule.typeis the error’s identity, and the only one: alwaysurn:radiumone:checkout-hpp:{slug}, for exampleurn:radiumone:checkout-hpp:session-invalid-state. The tables below list the whole value. Compare it as one string.titleis a short summary. Don’t branch on it.statusrepeats the HTTP status.detailis developer-facing English that can change, and may echo part of your request (for example the offending URL). Don’t parse it or show it to shoppers.instanceis the request path that produced the error.detailsis present for two types only:urn:radiumone:checkout-hpp:rate-limit-exceededcarries{ retry_after }(seconds), andurn:radiumone:checkout-hpp:gateway-unavailablecarries{ retry_after_ms }when the wait is known.
error object: type is the code. If you receive a type that isn’t listed here, treat it as not retryable — unless the response is a 429 or a 5xx, which you retry with back-off and the same order_reference.
Authentication and authorization
Missing, malformed, or mismatched credentials on any of the three operations.Validation
The request body failed a field rule or a cross-field check.Session state and idempotency
Session lookup, cancellation conflicts, and create-time idempotency. See Session lifecycle for the full state model behind these.Configuration and availability
Your merchant configuration or the gateway itself is unreachable. No session was created and nothing was charged.urn:radiumone:checkout-hpp:gateway-request-failed and urn:radiumone:checkout-hpp:gateway-unavailable both mean “safe to retry the same call” — they differ in cause (an upstream failure vs. payments being deliberately paused for a moment). Branch on the whole type, not on the HTTP status: gateway-unavailable is a 422, and every other 422 on this page is not retryable.Rate limits and server errors
Rate limits use a sliding window, not a fixed one. RadiumOne doesn’t publish the per-key and per-IP limits for authenticated calls — contact support if your peak checkout rate needs more.
A
GET session request without X-Api-Key returns a reduced public view (display fields only) that the hosted page itself uses. It’s limited per client IP and checkout to 30 requests per minute in production and 100 per minute in sandbox. Always send your secret key when you retrieve a session — see Verify the payment result.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.