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.

Envelope A — typed error

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.

Envelope B — legacy idempotency-pending

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.