Problem format
Both the Payments API and the Checkout API return errors as RFC 9457application/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 errortype 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.)
When you handle an error:
- Check
retry_allowedfirst. If it’s present, it decides whether you retry — not the HTTP status, and notdetail.falsemeans don’t send the operation again. A payment operation replayed with the samerequest_idoroperation_iddoesn’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). - Then match the whole
typeagainst the URNs you handle. - Treat a
typeyou don’t recognise as not retryable, unlessretry_allowedistrue. Log the full body, includingrequest_id, and fail the operation safely.
Validation error details
Most400 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 onstatus — 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), samerequest_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}, samerequest_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.
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, orDELETE(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 samerequest_idoroperation_id(a lookup). Token refresh, balance inquiry, and session calls each have their own recovery — see Retry when the service is unavailable.
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 fullcheckout:*/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 hitting429 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
429without aurn:radiumone:payment-gateway:*problem body didn’t come from RadiumOne — the request never reached it. Resend it with the samerequest_id(oroperation_id), afterRetry-Afterif 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 with201,data.status: "FAILED", andresponse_code: "99", and noRetry-After. Replaying the samerequest_idonly returns thatFAILEDtransaction again, so retry with a newrequest_idafter a short delay — nothing reached the issuer, so it can’t double-charge. This applies to"99"only: aFAILEDresult withresponse_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.