Skip to main content
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:
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.
  • type is the error’s identity, and the only one: always urn:radiumone:checkout-hpp:{slug}, for example urn:radiumone:checkout-hpp:session-invalid-state. The tables below list the whole value. Compare it as one string.
  • title is a short summary. Don’t branch on it.
  • status repeats the HTTP status.
  • detail is 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.
  • instance is the request path that produced the error.
  • details is present for two types only: urn:radiumone:checkout-hpp:rate-limit-exceeded carries { retry_after } (seconds), and urn:radiumone:checkout-hpp:gateway-unavailable carries { retry_after_ms } when the wait is known.
There’s no separate error-code field and no 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.
Last modified on October 25, 2026