> ## Documentation Index
> Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# Payment operation errors - Payments API

> Auth, validation, idempotency, transaction-state, and automatic-reversal errors for authorize, purchase, capture, void, and refund calls.

You'll hit these on `purchase`/`authorize`, capture, void, and refund calls.
Branch on the problem+json `type` URN and HTTP status returned in the body
— never on `title`, which is a display label. See [Problem format and
retries](/payments-api/errors/problem-format-and-retries) for the response
shape, the full HTTP status guide, and retry rules. The **Retry?** column
says whether to resend the request, following those rules and the linked
recovery page.

## Auth and validation

Credential, scope, and request-body problems — see [Fix rejected or
expired access tokens](/payments-api/handle-failures/authentication-failures)
for the walkthrough.

| URN | HTTP | Meaning | What to do | Retry? |
| - | - | - | - | - |
| <a id="gateway-validation-error" />`urn:radiumone:gateway:validation-error` | 400 | Body failed schema validation — see [Validation error details](/payments-api/errors/problem-format-and-retries#validation-error-details) for the per-field `errors` array | Fix the request body against the schema | No |
| <a id="auth-insufficient-scope" />`urn:radiumone:auth:insufficient-scope` | 403 | Your key's token lacks the scope this operation requires | [Fix rejected or expired access tokens](/payments-api/handle-failures/authentication-failures) | No |
| <a id="auth-outlet-binding-violation" />`urn:radiumone:auth:outlet-binding-violation` | 403 | The key is bound to a different outlet than the one requested | [Fix rejected or expired access tokens](/payments-api/handle-failures/authentication-failures) | No |
| <a id="gateway-token-expired" />`urn:radiumone:gateway:token-expired` | 401 | Your access token expired | [Fix rejected or expired access tokens](/payments-api/handle-failures/authentication-failures) | Once — after re-exchanging or refreshing the token |
| <a id="gateway-token-invalid" />`urn:radiumone:gateway:token-invalid` | 401 | Your access token failed verification | [Fix rejected or expired access tokens](/payments-api/handle-failures/authentication-failures) | Once — after re-exchanging or refreshing the token; if it fails again, treat it as a configuration problem |

## Idempotency

`request_id` and `operation_id` reuse conflicts — see [Handle replays and
idempotency conflicts](/payments-api/handle-failures/idempotent-replays-and-conflicts)
for the full walkthrough.

| URN | HTTP | Meaning | What to do | Retry? |
| - | - | - | - | - |
| <a id="transaction-idempotency-body-mismatch" />`urn:radiumone:transaction:idempotency-body-mismatch` | 409 | Same `request_id`, different body — or the same `request_id` reused for a different operation type | [Handle replays and idempotency conflicts](/payments-api/handle-failures/idempotent-replays-and-conflicts) | No — never safe to retry as-is; resend the stored original body, or mint a new key for a genuinely new attempt |
| <a id="tx-duplicate-operation" />`urn:radiumone:tx:duplicate-operation` | 409 | Same `operation_id` reused for a different operation on the same transaction | [Handle replays and idempotency conflicts](/payments-api/handle-failures/idempotent-replays-and-conflicts) | No — use one `operation_id` per operation |

## Transaction state (capture, void, refund)

Batch-state and lifecycle conflicts on a capture, void, or refund. See
[Handle capture failures](/payments-api/handle-failures/capture-failures)
and [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts).

| URN | HTTP | Meaning | What to do | Retry? |
| - | - | - | - | - |
| <a id="tx-capture-window-expired" />`urn:radiumone:tx:capture-window-expired` | 422 | Capture attempted after the window closed | [Handle capture failures](/payments-api/handle-failures/capture-failures) | No |
| <a id="tx-capture-amount-mismatch" />`urn:radiumone:tx:capture-amount-mismatch` | 422 | Capture `amount` doesn't equal the authorized amount | [Handle capture failures](/payments-api/handle-failures/capture-failures) — must equal the authorized amount exactly | No |
| <a id="tx-currency-mismatch" />`urn:radiumone:tx:currency-mismatch` | 422 | `amount.currency` on a capture or refund doesn't match the original transaction's currency | [Capture an authorization](/payments-api/capture) and [Refund a payment](/payments-api/refund) | No |
| <a id="tx-auth-expired-during-capture" />`urn:radiumone:tx:auth-expired-during-capture` | 409 | The authorization expired mid-flight, racing your capture | [Handle capture failures](/payments-api/handle-failures/capture-failures) | Depends — see [Retry rules](/payments-api/errors/problem-format-and-retries#retry-rules) |
| <a id="tx-void-on-non-open-batch" />`urn:radiumone:tx:void-on-non-open-batch` | 409 | Void attempted after the batch closed | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) — [refund](/payments-api/refund) instead | No |
| <a id="tx-refund-on-open-batch" />`urn:radiumone:tx:refund-on-open-batch` | 409 | Refund attempted while the batch is still open | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) — [void](/payments-api/void) instead | No |
| <a id="tx-amount-exceeds-captured" />`urn:radiumone:tx:amount-exceeds-captured` | 422 | Refund `amount` exceeds what's left (original minus prior refunds) | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) | No |
| <a id="tx-refund-window-expired" />`urn:radiumone:tx:refund-window-expired` | 422 | The refund window has elapsed since capture/settlement | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) | No |
| <a id="tx-refund-target-not-refundable" />`urn:radiumone:tx:refund-target-not-refundable` | 422 | The target transaction is no longer eligible (already refunded in full, voided) | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) | No |
| <a id="tx-invalid-state-transition" />`urn:radiumone:tx:invalid-state-transition` | 409 | The transaction's state doesn't allow the operation you requested | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) | Depends — see [Retry rules](/payments-api/errors/problem-format-and-retries#retry-rules) |
| <a id="transaction-void-reversal-pending" />`urn:radiumone:transaction:void-reversal-pending` | 409 | A void was refused because an earlier void on the same sale hasn't resolved yet | [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) — check the transaction status for the earlier void's outcome before voiding again | Yes, later — transient; only if the sale still isn't voided |

## Automatic reversals

See [Understand automatic reversals](/payments-api/handle-failures/automatic-reversals)
for the full walkthrough.

| URN | HTTP | Meaning | What to do | Retry? |
| - | - | - | - | - |
| <a id="transaction-reversal-limit-exceeded" />`urn:radiumone:transaction:reversal-limit-exceeded` | 409 | A reversal is stuck after repeated attempts | [Understand automatic reversals](/payments-api/handle-failures/automatic-reversals) — [contact support](/resources/support) | No |

## Next steps

<Columns cols={2}>
  <Card title="Problem format and retries" icon="triangle-alert" href="/payments-api/errors/problem-format-and-retries">
    The problem+json shape, HTTP status guide, and retry rules.
  </Card>

  <Card title="Payment method errors" icon="triangle-alert" href="/payments-api/errors/payment-method-errors">
    Loyalty, discovery, routing, and token errors.
  </Card>

  <Card title="Decline codes" icon="credit-card" href="/payments-api/errors/decline-codes">
    How a declined payment appears — that's not an error.
  </Card>

  <Card title="Handle failures" icon="life-buoy" href="/payments-api/handle-failures/overview">
    Find the right recovery page by symptom.
  </Card>
</Columns>