Skip to main content
Every error response from either API — Payments or Checkout — uses this same shape and these same retry rules. Read this page first, then go to Payment operation errors or Payment method errors for the URN catalog itself. For the response envelope and money shapes, see Request conventions.

Problem format

Both the Payments API and the Checkout API return errors as RFC 9457 application/problem+json bodies:
type is the URN to match against in code — never parse detail, which is a human-readable string that can change. Some errors add extension members to the body: retry_after is not a body field — when RadiumOne wants you to wait before retrying, it’s the Retry-After HTTP response header (seconds), most commonly on 429.

Error type URNs

Every Payments API error type has the form urn:radiumone:payment-gateway:{namespace}:{slug} — for example urn:radiumone:payment-gateway:tx:capture-window-expired — or urn:radiumone:payment-gateway:{slug} for an error that isn’t tied to one area, such as urn:radiumone:payment-gateway:validation-error. (Checkout API errors use urn:radiumone:checkout-hpp:{slug} — see Checkout API errors.)
Match the whole type. Compare it against the full URN — never a prefix, and never just the text after the last :. The same slug appears in several namespaces: urn:radiumone:payment-gateway:not-found and urn:radiumone:payment-gateway:token:not-found mean different things.
When you handle an error:
  1. Check retry_allowed first. If it’s present, it decides whether you retry — not the HTTP status, and not detail. false means don’t send the operation again. A payment operation replayed with the same request_id or operation_id doesn’t send it again — RadiumOne answers it from what it recorded, or, for a capture, void, or referenced refund whose outcome it didn’t record, from what the card network stored — so that replay is a lookup and stays safe (see Retry rules).
  2. Then match the whole type against the URNs you handle.
  3. Treat a type you don’t recognise as not retryable, unless retry_allowed is true. Log the full body, including request_id, and fail the operation safely.

Validation error details

Most 400 urn:radiumone:payment-gateway:validation-error responses add an errors array alongside detail — one entry per invalid field:
Rely on pointer/parameter and code to drive logic — not the wording of either detail (the top-level one or a field’s own), which can change. errors is present only when the request failed schema validation — absent on other 400s. It’s present when the request itself doesn’t match the endpoint’s schema: a missing or wrongly typed body field, a value that breaks a format or length rule, or an invalid query or path parameter. It’s absent when the 400 comes from a business check that runs after schema validation passed — same URN, same status, no errors array. Always handle errors being absent rather than assuming every 400 urn:radiumone:payment-gateway:validation-error carries one.

HTTP status guide

Retry rules

Any 2xx response is a result you must branch on status — never on response_code (that’s the verbatim host/acquirer code; useful for support tickets, not for your app logic). In short: timeouts, 5xx, and PENDING are retried with the same key — the identical request, with backoff. That holds for every payment operation even when the 5xx says retry_allowed: false (switch-timeout, or database-unavailable on anything but a GET), because a same-key replay is a lookup, not a resend:
  • Purchase, authorize, and standalone refund (POST /v1/transactions/refund), same request_id: RadiumOne returns the attempt it recorded and never sends it again.
  • Capture and void (same operation_id) and referenced refund (POST /v1/transactions/refund/{transaction_id}, same request_id): RadiumOne returns the recorded outcome. If the operation was sent but its outcome wasn’t recorded, it asks the card network for the outcome the network stored and returns that; it sends the operation only if the network never received it.
A replay can return PENDING or REVERSAL_PENDING until the outcome settles; the webhook confirms the final one. retry_allowed: false still rules out the other kind of retry: a new key, or a different operation on the same transaction. While a capture, void, or refund has no recorded outcome, a follow-up with a different key on that transaction returns 409 urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt (retry_allowed: false) — resend the request its pending_operation_id names first (see Replays and idempotency conflicts). A decline or a validation/business error is not retried with the same key — fix the input, or start a genuinely new attempt with a new key. A 409 urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch means the key was reused with a different body — it is never safe to retry as-is.

Database unavailable

503 urn:radiumone:payment-gateway:database-unavailable can come from any endpoint. It’s the one 5xx you don’t resend blind:
  • GET (retry_allowed: true): retry after a delay.
  • POST, PATCH, or DELETE (retry_allowed: false): don’t resend blind — what’s safe depends on the endpoint. Every payment operation — purchase, authorize, capture, void, and both refunds — is replayed with the same request_id or operation_id (a lookup). Token refresh, balance inquiry, and session calls each have their own recovery — see Retry when the service is unavailable.
See Handle timeouts and unknown outcomes and Retry when the service is unavailable for the full walkthroughs.

Errors from other products

3D Secure errors

3D Secure statuses, SDK errors, and gateway errors have their own full tables — see Authentication results, the single reference for that family. This page doesn’t duplicate them. If you’re bringing your own 3DS provider’s evidence, see Handle 3DS failures with your own provider.

Checkout API errors

The Checkout API (Hosted checkout) has its own error pages — see Checkout API errors for the full checkout:*/session:*/security:* URN catalog, or the Hosted checkout Errors section for outcomes and redirect/embedded signals.

Rate limits

RadiumOne doesn’t publish specific rate-limit numbers. If you’re consistently hitting 429 urn:radiumone:payment-gateway:rate-limit-exceeded, retry after the response’s Retry-After header, then contact support to discuss your integration’s traffic pattern. Two other cases look like rate limiting but are handled differently:
  • A 429 without a urn:radiumone:payment-gateway:* problem body didn’t come from RadiumOne — the request never reached it. Resend it with the same request_id (or operation_id), after Retry-After if the response has one.
  • The payment network was busy. RadiumOne applies no rate limit to purchase, authorize, or refund calls, but the payment network behind it can refuse a request before anything reaches the card issuer. RadiumOne doesn’t pass that on as a 429: it answers a purchase, authorization, or standalone refund with 201, data.status: "FAILED", and response_code: "99", and no Retry-After. Replaying the same request_id only returns that FAILED transaction again, so retry with a new request_id after a short delay — nothing reached the issuer, so it can’t double-charge. This applies to "99" only: a FAILED result with response_code: "**" means the network rejected the request itself, and it fails the same way until you fix the request.

Next steps

Payment operation errors

Auth, validation, idempotency, transaction-state, and reversal errors.

Payment method errors

Loyalty, discovery, routing, and token errors.

Decline codes

How a declined payment appears, and how to handle it — that’s not an error.

Handle failures

Find the right recovery page by symptom.
Last modified on October 25, 2026