503 or 500 with no business meaning behind it — a dependency was down, or something failed unexpectedly on RadiumOne’s side.
TL;DR — Check
retry_allowed first. 503/500 on a create-type request usually behaves like a timeout: retry with the same idempotency key, with backoff — never a new one. A 5xx with retry_allowed: false — such as database-unavailable on anything but a GET — means don’t send the operation again, but every payment operation (purchase, authorize, capture, void, and both refunds) can still be replayed with the same request_id or operation_id: the replay is a lookup, not a resend. Other endpoints have their own recovery: see Database unavailable.When this happens
503 urn:radiumone:payment-gateway:service-unavailable— a downstream service RadiumOne depends on is unreachable (for example, the one that verifies your access token), or the service is starting up. It fails before any work is done, soretry_allowedistrue: retry after a delay. The one exception isPOST /v1/auth/token/refresh(retry_allowed: false): the refresh token has already been rotated and revoked, so get a new token with your API key instead (below).503 urn:radiumone:payment-gateway:vault-unavailable— the encryption-key service backing card tokenization is unavailable. RadiumOne returns this generic form deliberately, without leaking which key or vault path failed.503 urn:radiumone:payment-gateway:database-unavailable— RadiumOne couldn’t reach its database. Any endpoint can return it — see Database unavailable below.503 urn:radiumone:payment-gateway:request-deadline-exceeded— RadiumOne stopped processing the request after its time limit (about 85 seconds).retry_allowedfollows the method, likedatabase-unavailable:trueon aGET(such as the status inquiry), which only reads, so retry after a delay;falseon anything else. On a payment operation the outcome is unknown, so replay it with the same key, like a timeout.503 urn:radiumone:payment-gateway:routing:acquirer-circuit-open— on a purchase, authorize, or standalone refund, every acquirer that could take the request is briefly out of service. Nothing was sent and no transaction was created;retry_allowed: true. Retry after a delay — see Fix operations unavailable for your outlet.503 urn:radiumone:payment-gateway:routing:original-acquirer-unavailable— on a capture, void, or referenced refund, the acquirer that processed the original transaction is temporarily unavailable. Nothing was sent; retry after a delay with the same key.500 urn:radiumone:payment-gateway:internal-error— an unexpected failure that isn’t one of the above.
What you see
What to do
1
Check for a retry signal first
If the error body carries
retry_allowed, or the response has a Retry-After header, honor it directly — see Problem format and retries: retry rules.2
Otherwise, branch on URN and retry_allowed, never on the HTTP code alone
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).After a timeout or a
5xx, replay with the same key. For every payment operation — purchase, authorize, capture, void, and both refunds — a replay of the identical request with the same request_id or operation_id is a lookup, not a resend, so it’s safe even after a 5xx that says retry_allowed: false (switch-timeout, database-unavailable). RadiumOne returns the outcome it recorded. If a capture, void, or referenced refund was sent but its outcome wasn’t recorded, RadiumOne asks the card network for the stored outcome instead of sending it again, and sends it only if the network never received it — so nothing is applied twice. A replay can return PENDING or REVERSAL_PENDING until the outcome settles. A request RadiumOne refused before it reached the card network (for example with device-settling or device-busy) is run again on the same transaction instead of returning a stored result — no second transaction is created. A capture that timed out after it may have reached the card network is reversed — the capture, never the authorization under it: while that reversal is open (REVERSAL_PENDING), a same-operation_id retry gets 409 tx:invalid-state-transition; once it clears, the hold is back to AUTHORIZED and the retry is sent as a new capture attempt. A capture that timed out before it left RadiumOne is sent as a new attempt on a same-operation_id retry — nothing was sent the first time. A void that timed out is reversed too: while that reversal is open, a retry gets 409 transaction:void-reversal-pending (retry_allowed: true); once it clears, the sale is back to CAPTURED and the retry is sent as a new attempt. While that earlier capture, void, or refund is unresolved, a follow-up with a different key on the same transaction gets 409 urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt: resend the pending request first. See Handle timeouts and unknown outcomes.PENDING means the outcome isn’t known yet — most often after a processor timeout. Don’t assume success or failure. Recover it one of two ways:- Wait for a webhook (
payment.*,authorization.*,refund.*— see Webhook event types). - Poll
GET /v1/transactions/{id}/status— it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it readsPENDINGorREVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request;INCONSISTENTmeans stop and contact support; anything else is final. See Check a transaction’s status.
id yet — a client-side timeout before the first response arrived — replay the same purchase, authorize, or refund with the same request_id and body. The replay is a lookup, not a resend: it returns the stored transaction and its id, whatever status it’s reached, including PENDING or REVERSAL_PENDING. A capture or void replayed with the same operation_id works the same way, and for a capture, void, or referenced refund whose outcome wasn’t recorded, RadiumOne checks with the card network before sending anything. Never re-submit with a new idempotency key just because the first attempt is slow — that risks a second charge for the same order.3
Retry with backoff, using the same key
Retry a purchase/authorize/refund with the same
request_id, or a capture/void with the same operation_id, when retry_allowed is true or absent. Add jittered backoff between attempts rather than retrying immediately. After retry_allowed: false, replay a payment operation the same way — it’s a lookup, not a resend — but follow the endpoint’s own recovery for anything else; see Database unavailable.4
Fall back to timeout handling if retries don't resolve it
If the outcome still isn’t clear after a retry, follow Handle timeouts and unknown outcomes — wait for the confirming webhook (recommended), or check status now if you don’t use webhooks or need an answer sooner, rather than continuing to retry indefinitely.
Database unavailable
503 urn:radiumone:payment-gateway:database-unavailable means RadiumOne
couldn’t reach its database, or a query couldn’t run. It can come from any
endpoint, and retry_allowed depends on the method:
retry_allowed: false doesn’t mean every call is stuck. What’s safe depends on
the endpoint:
To settle a payment operation whose same-key replay still doesn’t give you a
final outcome:
1
Wait for the webhook
The confirming webhook (
payment.*, authorization.*, refund.*) carries your order_reference and the transaction id, so it tells you the outcome even though the response didn’t — see Webhook event types.2
Check the status if you already have a transaction id
For a capture, void, or referenced refund you already know the transaction
id: call status inquiry (a GET, so it’s safe to retry) to see where the transaction stands.3
Still no answer? Contact support before you try again
If no webhook arrives and you have no transaction
id to look up, contact support with your order_reference, request_id, and the approximate time. RadiumOne doesn’t offer a list-by-order_reference lookup. Only start a new attempt, with a new request_id, once you know the first one didn’t charge the shopper.Related
Problem format and retries
The full retry-rules reference.
Handle timeouts and unknown outcomes
The idempotent-retry pattern this page reuses.