> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Error codes
> Look up the error codes returned by the Global Acquiring API, where they appear, and what to do when you encounter them.
When a Global Acquiring API call fails, the gateway returns a non-2xx HTTP status with a JSON error body. Use this page to identify what went wrong and how to recover.
## Error response formats
The Global Acquiring API uses **two response envelopes**. Which one you receive depends on which handler processed the request.
Almost every error the Global Acquiring API returns uses this envelope. The `type` field determines the HTTP status (see [Error types](#error-types)).
```json theme={null}
{
"type": "payment_error",
"code": "retrieve_payment_intent_failed",
"message": "Retrieve payment intent failed"
}
```
| Field | Meaning |
| --------- | ----------------------------------------------------------------------------------- |
| `type` | High-level category. Maps to HTTP status (see [Error types](#error-types)). |
| `code` | Machine-readable string identifier. Use for programmatic handling. |
| `message` | Human-readable description. Safe to log, not safe to surface verbatim to end-users. |
When a request reuses an `Idempotency-Key` that is still being processed, the idempotence middleware returns a flat shape where `code` is a numeric literal and the HTTP status is 400. No `type` field is present.
```json theme={null}
{
"code": 200,
"message": "Request is processing, please try again later."
}
```
| Field | Meaning |
| --------- | ------------------------------------------------------------------------------------- |
| `code` | Numeric literal. `200` is emitted only while the original request is still in flight. |
| `message` | Human-readable description. |
When handling responses, branch on whether a `type` field is present to pick the right envelope. Envelope B never carries `type`.
## Error types
Envelope A groups codes into types, each of which maps to a fixed HTTP status.
| `type` | HTTP | When it appears |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_request_error` | 400 | Request failed validation. |
| `idempotency_error` | 400 | Idempotency key format invalid or mismatched. |
| `account_error` | 400 | Account or bank-account resource rule violated. |
| `customer_error` | 400 | Customer resource rule violated. |
| `payment_error` | 400 | PaymentIntent, PaymentAttempt, or payment-link rule violated. |
| `refund_error` | 400 | Refund resource rule violated. |
| `payout_error` | 400 | Payout resource rule violated. |
| `product_error` | 400 | Merchant product configuration prevents the operation. |
| `not_found` | 400 | Requested resource id was not found on the connected account. |
| `unauthorized_error` | 401 | API key or client secret missing, malformed, or expired. |
| `api_error` | 400 / 429 / 500 | Catch-all for gateway-internal or risk-control errors; HTTP 500 when `code` is `api_error`, 429 when `velocity_limit_exceeded`. |
Envelope B does not carry a `type` field; branch on whether `code` is numeric (Envelope B) or a string (Envelope A) to distinguish cases.
## Common errors
These can appear on any authenticated endpoint.
### Envelope A (typed errors)
| `code` | `type` | Message | What to do |
| -------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_parameter` | `invalid_request_error` | *(varies — `parameter is invalid` for JSON/query bind failure, or `Invalid request parameters: ` for validator failures)* | Check the request body against the endpoint's API reference — one or more fields failed JSON binding or schema validation. When the message names a field, correct that field and retry. |
| `missing_parameter` | `invalid_request_error` | Mandatory parameter is missing | Supply the required path parameter or body field noted in the message. Most commonly this means a missing `{id}` segment or an empty required field in the request body. |
| `unauthorized_error` | `unauthorized_error` | *(varies — e.g. `auth token is not empty`, `invalid auth token format`, `auth token is expired`)* | Obtain a fresh token from **Request an access token** and send it in the `x-auth-token` header. Tokens expire — refresh before retrying. |
| `account_not_found` | `account_error` | Account not found or deactivated | Verify the merchant account resolved from your access token is active. If the account was recently created or suspended, contact UQPAY support before retrying. |
| `invalid idempotency key format` | `idempotency_error` | Idempotency key is invalid | Send a non-empty `Idempotency-Key` header that matches the format documented for the endpoint (typically a UUID). Regenerate the key and retry. |
| `api_error` | `api_error` | An internal error occurred, please try again. | Retry the request with the same `Idempotency-Key` after a short backoff. If the error persists, contact UQPAY support with the `request_id` from the response headers. |
### Envelope B (legacy idempotency-pending)
| `code` | Message | What to do |
| ------ | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Request is processing, please try again later. | Retry shortly with the same `Idempotency-Key` — the original request is still being processed and the final response will be returned once it completes. |
## Resource errors
### Payment errors
Create a PaymentIntent · Retrieve a PaymentIntent · Update a PaymentIntent · Confirm a PaymentIntent · Capture a PaymentIntent · Cancel a PaymentIntent · List all PaymentIntents · Retrieve a PaymentAttempt · List all PaymentAttempts
*Envelope A types: `payment_error`, `invalid_request_error`, `product_error`, `not_found`.*
**Envelope A**
| `code` | Message | Typical endpoints | What to do |
| --------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_payment_intent_failed` | Create payment intent failed | Create a PaymentIntent | Gateway-internal failure while persisting the PaymentIntent. Retry with the same `Idempotency-Key`; if it keeps failing, contact UQPAY support with the `request_id`. |
| `create_payment_attempt_failed` | Create payment attempt failed | Create a PaymentIntent · Confirm a PaymentIntent | Gateway-internal failure while creating the attempt record. Retry with the same `Idempotency-Key`; contact support if the error repeats. |
| `confirm_payment_intent_failed` | Confirm payment intent failed | Create a PaymentIntent · Confirm a PaymentIntent | Confirmation to the channel failed. Use **Retrieve a PaymentIntent** to check the current `status` before retrying — the attempt may already be in flight. |
| `retrieve_payment_intent_failed` | Retrieve payment intent failed | Retrieve a PaymentIntent · Update a PaymentIntent · Confirm a PaymentIntent · Capture a PaymentIntent · Cancel a PaymentIntent · Create a refund | Verify the PaymentIntent `id` in the URL exists and belongs to the authenticated account. Do not strip the `pi_` prefix. |
| `retrieve_payment_attempt_failed` | Retrieve payment attempt failed | Retrieve a PaymentAttempt · Capture a PaymentIntent · Cancel a PaymentIntent · Create a refund | Verify the `payment_attempt` id exists on the referenced PaymentIntent. Use **Retrieve a PaymentIntent** to list valid attempt ids. |
| `update_payment_intent_failed` | Update payment intent failed | Update a PaymentIntent | Check the PaymentIntent `status` via **Retrieve a PaymentIntent** — only intents in `requires_payment_method` or `requires_confirmation` accept updates. |
| `capture_payment_intent_failed` | Capture payment intent failed | Capture a PaymentIntent | Gateway-internal failure while forwarding the capture to the channel. Use **Retrieve a PaymentIntent** to confirm whether the capture succeeded before retrying. |
| `capture_amount_invalid` | Amount requested is inconsistent with order amount, Please enter the correct amount. | Capture a PaymentIntent | Set `amount_to_capture` to a value between zero and the PaymentIntent's authorized amount. For full capture, omit the field entirely. |
| `cancel_payment_intent_failed` | Cancel payment intent failed | Cancel a PaymentIntent | Verify the PaymentIntent is still cancellable (status `requires_capture` or earlier) via **Retrieve a PaymentIntent**. Completed or already-cancelled intents cannot be cancelled. |
| `invalid_order_status` | Invalid order status | Update a PaymentIntent · Capture a PaymentIntent · Cancel a PaymentIntent · Create a refund | The PaymentIntent's current `status` does not permit this operation. Use **Retrieve a PaymentIntent** to check status, then call the appropriate endpoint for that state. |
| `expired_order` | Expired payment intent | Update a PaymentIntent | The PaymentIntent has passed its expiry window. Create a new PaymentIntent instead of updating this one. |
| `order_cancelled` | Order cancelled | Cancel a PaymentIntent | The PaymentIntent is already in `canceled` status. No further action is required. |
| `operation_pending` | Operation pending! Do not repeat submissions! | Cancel a PaymentIntent | A prior cancel is still processing. Wait briefly and call **Retrieve a PaymentIntent** to confirm the final status before retrying. |
| `repeat_payment_request` | Operation failed. Payment request has been completed for the order. No need to repeat operation. | Capture a PaymentIntent | The PaymentIntent has already been captured. Call **Retrieve a PaymentIntent** to read the resulting state — no retry needed. |
| `invalid_payment_method` | invalid pay method | Create a PaymentIntent · Confirm a PaymentIntent | Use a `payment_method` value that is enabled for your account and supported for the order currency and customer country. Check your merchant dashboard for the enabled payment methods. |
| `invalid_return_url` | Invalid return url | Create a PaymentIntent | Supply an absolute HTTPS URL for `return_url`. It must be reachable and must not contain unencoded spaces or fragments that break URL parsing. |
| `invalid_description` | Invalid description | Create a PaymentIntent | Shorten `description` to within the documented length (256 characters) and remove any disallowed characters. |
| `invalid_order_amount` | Invalid order amount | Create a PaymentIntent | Send `amount` as a positive integer in the smallest currency unit (for example cents for USD). Check minimum and maximum limits for the selected `payment_method`. |
| `invalid_order_currency` | Invalid order currency | Create a PaymentIntent · Confirm a PaymentIntent | Use an ISO 4217 currency code that your account supports for the selected `payment_method`. Some methods (for example PayNow) only accept specific currencies. |
| `invalid_payment_orders` | Invalid payment orders | Create a PaymentIntent | The sub-order breakdown in `payment_orders` does not sum to the top-level `amount`, or contains invalid entries. Verify each sub-order's amount and currency. |
| `not_found_id` | Not Found ID | Retrieve a PaymentIntent | The PaymentIntent `id` does not exist on this account. Double-check the id value and confirm you are calling with the correct API key. |
| `product_not_found` | Product not found or inactive | Create a PaymentIntent · Confirm a PaymentIntent · Cancel a PaymentIntent | The account's product configuration for this `payment_method` is missing or inactive. Contact UQPAY support to enable the product. |
| `3ds_required` | 3DS Required | Create a PaymentIntent · Confirm a PaymentIntent | The card issuer requires 3-D Secure for this transaction. Re-submit with `3ds.required = true` and handle the returned challenge URL in the cardholder's browser. |
| `require_payment_pii` | *(varies — `invalid payment method body`, `invalid payer info`, `invalid payer identifier`, ...)* | Create a PaymentIntent · Confirm a PaymentIntent | The selected `payment_method` requires additional payer details (name, email, document id, or billing address). Populate the method-specific PII fields called out in the message. |
| `retrieve_refund_failed` | Retrieve refund failed | Cancel a PaymentIntent · Create a refund · Retrieve a refund | Verify the refund `id` belongs to this account. On cancel/refund flows, this surfaces when a previously requested refund cannot be re-read — retry after a brief delay. |
| `payment_link_not_found` | Payment link not found | Create a PaymentIntent | The `payment_link` id in the request is unknown. Confirm the link exists for this account and has not been deleted. |
| `payment_link_expired` | This link can no longer accept payments. Contact the seller for more information. | Create a PaymentIntent | The payment link has passed its `expires_at` timestamp. Ask the merchant to issue a new link. |
| `payment_link_inactive` | This link can no longer accept payments. Contact the seller for more information. | Create a PaymentIntent | The payment link has been deactivated. Ask the merchant to reactivate it or issue a new one. |
| `payment_link_access_number_not_enough` | This link can no longer accept payments. Contact the seller for more information. | Create a PaymentIntent | The payment link has reached its configured usage cap. Ask the merchant to raise the access limit or issue a new link. |
| `payment_link_parameters_error` | Payment link parameters error | Create a PaymentIntent | Request parameters (amount, currency, or customer info) do not match what the payment link allows. Align the request with the link's configuration. |
### Refund errors
Create a refund · Retrieve a refund · List all refunds
*Envelope A types: `refund_error`, `payment_error`, `invalid_request_error`, `api_error`.*
**Envelope A**
| `code` | Message | Typical endpoints | What to do |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_refund_failed` | Create refund failed | Create a refund | Gateway-internal failure while creating the refund. Retry with the same `Idempotency-Key`; if the error repeats, contact UQPAY support with the `request_id`. |
| `refund_processing` | Refund is processing, please try again after | Create a refund | A refund on this PaymentIntent is already in flight. Wait for its outcome (via **Retrieve a refund** or the refund webhook) before submitting another. |
| `refund_stat_failed` | Find refund order failed | Create a refund | Verify the `payment_intent` referenced by the refund exists and is in a refundable status. |
| `refund_amount_exceeded` | Refund amount exceeded original transaction amount | Create a refund | Reduce `amount` so that the sum of all refunds on this PaymentIntent does not exceed the captured amount. |
| `refund_amount_invalid` | Refund amount invalid | Create a refund | Send `amount` as a positive integer in the smallest currency unit. It must be greater than zero and no larger than the remaining refundable amount. |
| `retrieve_refund_failed` | Retrieve refund failed | Retrieve a refund · Create a refund · Cancel a PaymentIntent | Verify the refund `id` belongs to this account. Retry after a short delay if the refund was just created and may not yet be visible. |
| `api_error` | Please use the payment cancel endpoint | Create a refund | The PaymentIntent is still in a state where refund is not applicable — call **Cancel a PaymentIntent** instead. |
| `invalid_parameter` | *(varies — `invalid start_time`, `invalid end_time`, `the end_time cannot be earlier than the start_time`, `the start_time and end_time cannot differ by more than 90 days`)* | List all refunds | Supply RFC 3339 timestamps for `start_time` and `end_time`, ensure `end_time` is after `start_time`, and keep the window within 90 days. |
### Customer errors
Create a customer · Get a customer · Update a customer · List customers
*type: `customer_error`*
**Envelope A**
| `code` | Message | Typical endpoints | What to do |
| -------------------------- | ------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_customer_failed` | Create customer failed | Create a customer | Gateway-internal failure while persisting the customer. Retry with the same `Idempotency-Key`; if it keeps failing, contact UQPAY support with the `request_id`. |
| `update_customer_failed` | Update customer failed | Update a customer | Verify the customer `id` exists on this account and that the updated fields pass schema validation. Retry with the same `Idempotency-Key`. |
| `retrieve_customer_failed` | Retrieve customer failed | Get a customer | Verify the customer `id` exists and belongs to the authenticated account. |
### Payout errors
Create Payout · Retrieve Payout · List all Payouts · Retrieve Balance · List Balances · Create Bank Account · Retrieve Bank Account · Update Bank Account · List all Bank Accounts
*Envelope A types: `payout_error`, `account_error`, `product_error`, `api_error`.*
**Envelope A**
| `code` | Message | Typical endpoints | What to do |
| ------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_payout_failed` | Create payout failed | Create Payout | Gateway-internal failure while creating the payout. Retry with the same `Idempotency-Key`; if it repeats, contact UQPAY support with the `request_id`. |
| `payout_not_found` | payout not found | Retrieve Payout | Verify the payout `id` exists and belongs to the authenticated account. |
| `payout_settlement_account_not_found` | No account settlement for this currency | Create Payout | Your account does not have a settlement account configured for this currency. Contact UQPAY support to enable payout in the requested currency. |
| `invalid_currency` | Invalid currency | Retrieve Balance · Create Bank Account · Create Payout | Use an ISO 4217 currency code that matches your account's enabled currencies. Check your merchant dashboard for the list of supported currencies. |
| `insufficient_balance` | Merchant's available balance is insufficient | Create Payout | Reduce the payout `amount` or top up the balance before retrying. Use **List Balances** to read the current available balance for the requested currency. |
| `merchant_account_invalid` | Merchant Account Invalid | Create Payout | The merchant account is not configured for payouts. Contact UQPAY support to enable the payout product. |
| `disabled_transfer_type` | This type of payout is disabled by the merchant (e.g., auto-withdrawal turned off) | Create Payout | The account has disabled this `transfer_type` (for example auto-withdrawal). Enable the setting in the merchant dashboard or pick a different `transfer_type`. |
| `velocity_limit_exceeded` | Transaction frequency/amount exceeds risk control thresholds (HTTP 429) | Create Payout | Slow down payout creation and retry after the rate-limit window. If limits are consistently hit, contact UQPAY to discuss raising them. |
| `product_not_found` | Product not found or inactive | Create Payout | The payout product is not active for your account. Contact UQPAY support to enable it. |
| `bank_account_not_found` | Bank account not found | Retrieve Bank Account · Update Bank Account | Verify the bank-account `id` exists and belongs to the authenticated account. |
| `bank_account_already_exists` | Bank account already exists for this currency | Create Bank Account | Update the existing bank account for this currency via **Update Bank Account** instead of creating a new one. Only one bank account per currency is allowed. |
| `create_bank_account_failed` | Create bank account failed | Create Bank Account | Gateway-internal failure while persisting the bank account. Retry with the same `Idempotency-Key`; contact support if the error repeats. |
| `update_bank_account_failed` | Update bank account failed | Update Bank Account | Verify the bank-account `id` and the updated fields pass schema validation. Retry with the same `Idempotency-Key`. |
| `internal_error` | Internal Error: Please contact support for assistance | Retrieve Payout · List Balances · Create Bank Account · List all Bank Accounts | Retry with the same `Idempotency-Key` after a short backoff. If the error persists, contact UQPAY support with the `request_id` from the response headers. |
| `invalid_parameter` | Invalid request parameters: `` | Retrieve Payout · Update Bank Account · Create Payout | Correct the field named in the message and retry. The validator calls out the specific field that failed schema validation. |