Skip to main content
A call returns 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, so retry_allowed is true: retry after a delay. The one exception is POST /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_allowed follows the method, like database-unavailable: true on a GET (such as the status inquiry), which only reads, so retry after a delay; false on 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

These URNs don’t all carry an explicit retry_allowed extension. When it’s there, follow it. When it isn’t, treat a 503/500 on a create-type request the same as a timeout — the request may have partially processed before the failure surfaced. Never retry with a new idempotency key.

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.
Balance inquiry also takes a request_id field, but it isn’t an idempotency key — there’s no dedup or replay store. Every call re-queries the rewards host, even with the same request_id.
Keys are 8–64 characters, [a-zA-Z0-9-] only, unique per merchant account. Generate one key per order attempt and persist it to your database before you send the first request — never mint a new key just to retry the same attempt. See Prevent duplicate payments.
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:
  1. Wait for a webhook (payment.*, authorization.*, refund.* — see Webhook event types).
  2. Poll GET /v1/transactions/{id}/status — it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it reads PENDING or REVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request; INCONSISTENT means stop and contact support; anything else is final. See Check a transaction’s status.
If you don’t have the transaction 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.

Problem format and retries

The full retry-rules reference.

Handle timeouts and unknown outcomes

The idempotent-retry pattern this page reuses.
Last modified on September 29, 2026