Error codes - UQPAY Developer Docs

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.

Envelope A — typed error
Envelope B — legacy idempotency-pending

Almost every error the Global Acquiring API returns uses this envelope. The type field determines the HTTP status (see Error types).

{
  "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).
`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.

{
  "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: <field>` 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

Endpoints

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

Endpoints

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

Endpoints

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

Endpoints

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: `<field>`	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.

​Error response formats

​Error types

​Common errors

​Envelope A (typed errors)

​Envelope B (legacy idempotency-pending)

​Resource errors

​Payment errors

​Refund errors

​Customer errors

​Payout errors

Error response formats

Error types

Common errors

Envelope A (typed errors)

Envelope B (legacy idempotency-pending)

Resource errors

Payment errors

Refund errors

Customer errors

Payout errors