Error codes

When a Card Issuance 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 Card Issuance API uses two response envelopes. Which one you receive depends on which handler processed the request.

Envelope A — string code
Envelope B — legacy flat 400

Most card and cardholder errors return this envelope. type determines the HTTP status.

{
  "type": "card_error",
  "code": "card_not_found",
  "message": "card not found or deactivated"
}

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.

A subset of handlers — chiefly older card operations that pre-date the typed error system — return a flat shape where code is the HTTP status as a string and message carries the error sentence.

{
  "code": "400",
  "message": "Create card error"
}

Field	Meaning
`code`	HTTP status as a string (`"400"` for validation/business errors, `"429"` for rate-limited requests). Branch on the `message` field for finer-grained handling.
`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.
`card_error`	400	Card resource rule violated.
`cardholder_error`	400	Cardholder resource rule violated.
`account_error`	400	Account / product / balance rule violated.
`idempotency_error`	400	Idempotency key replay or mismatch.
`unauthorized_error`	401 / 403	API key missing, invalid, or lacks permission. `code` is `unauthorized_error` for 401 and `forbidden` for 403.
`api_error`	500	Internal server error. Safe to retry with the same `Idempotency-Key`.

Envelope B does not carry a type field; branch on the message to distinguish cases.

Common errors

These can appear on any authenticated endpoint.

Envelope A (string codes)

`code`	`type`	Message	What to do
`invalid_request_error`	`invalid_request_error`	(varies — field path and validation rule in `message`)	TODO
`unauthorized_error`	`unauthorized_error`	Token expired, IP not allowed, or access token dependencies unavailable	Request a new access token via Access Token, confirm your caller IP is on the allow-list, and retry with a fresh `x-auth-token` header.
`forbidden`	`unauthorized_error`	Returned when the API key lacks permission (currently guards `GET /cards/{id}/secure`)	Ask your UQPAY solutions engineer to enable the sensitive-card-details permission on your API key, then retry.
`api_error`	`api_error`	(varies — generic internal server error)	TODO
`account_not_found`	`account_error`	account not found or deactivated	Verify the `client_id` / API key you are using belongs to an active UQPAY account. If the account was recently created, confirm onboarding is complete.
`sub_account_not_found`	`account_error`	sub-account associated with the on-behalf-of not found or deactivated	Verify the `on-behalf-of` header targets an existing, active sub-account under your parent account, or omit the header to act as the parent account.
`user_not_found`	`account_error`	user associated with account not found or deactivated	Confirm the user bound to your API key is still active. Contact your UQPAY solutions engineer if the user was recently disabled.
`request_being_processed`	`idempotency_error`	request is being processed	Retry shortly with the same `Idempotency-Key` — the original request is still being processed. Do not change the request body between retries.
`invalid_key_format`	`idempotency_error`	invalid idempotency key format	Provide an `Idempotency-Key` header that is a non-empty string up to 255 characters (a UUID v4 is recommended).
`key_mismatch_account`	`idempotency_error`	key does not belong to account	The `Idempotency-Key` was previously used by a different account — generate a fresh key scoped to the current account.
`key_mismatch_api`	`idempotency_error`	api associated with key is not the original	Reuse the `Idempotency-Key` only on the exact same endpoint + method that first used it. Generate a new key for a different endpoint.

Envelope B (legacy flat 400)

`code`	Message	What to do
`400`	Request parameters invalid	Verify every required field is present and correctly typed against the endpoint’s schema in the API Reference.
`400`	Params JSON error	The request body failed JSON parsing — check for trailing commas, unescaped quotes, or a missing `Content-Type: application/json` header.
`400`	Account does not exist.	Confirm the API key belongs to an active account and that the resolved account has not been deactivated.
`400`	An internal error occurred, please try again	Retry the request with the same `Idempotency-Key` after a short backoff. If the error persists, contact your UQPAY solutions engineer with the request timestamp.
`400`	Login expired	Request a new access token via Access Token and retry with the fresh `x-auth-token`.
`429`	Request is too frequent	Back off and retry with exponential delay. Sensitive-card and PAN-token endpoints are per-card rate-limited — do not poll tighter than a few seconds apart.

Resource errors

Card errors

Endpoints

Create Card · List Cards · Update Card · Retrieve Card · Update Card Status · Retrieve Sensitive Card Details · Create PAN Token · Card Recharge · Card Withdraw · Retrieve Card Order · Activate Card · Reset Card PIN · Assign Card

Envelope A types: card_error, plus account_error (product_not_found, account_balance_error) during card creation. Envelope A

`code`	Message	Typical endpoints	What to do
`card_not_found`	card not found or deactivated	Any endpoint that takes `{card_id}`	Verify the `card_id` exists under your account and is not cancelled. Use List Cards or Retrieve Card to confirm.
`operation_not_authorized`	requested card operation type is not authorized	Create Card	Your account does not have permission to issue this card type — contact your UQPAY solutions engineer to enable it on your account.
`risk_control_not_allowed`	risk control setting is not allowed	Create Card	Remove or adjust the `risk_controls` entries that exceed what your card product permits. Supported configurations are listed in the Card products capability matrix.
`currency_not_allowed`	card currency is not allowed	Create Card	Set `currency` to one of the currencies your selected card product supports. Check the product configuration with your UQPAY solutions engineer.
`limit_out_of_range`	card limit is either less than minimum card limit or greater than maximum card limit	Create Card	Set `spending_controls.spending_limit` between the product’s configured min and max. The bounds are set per card product — confirm them with your UQPAY solutions engineer.
`cardholder_quota_exceeded`	card quota of cardholder exceeds limit	Create Card	This cardholder has hit the maximum number of active cards allowed. Cancel an existing card via Update Card Status before issuing another, or use a different cardholder.
`account_quota_exceeded`	card quota of account exceeds limit	Create Card	Your account-wide card quota is reached. Cancel unused cards via Update Card Status, or contact your UQPAY solutions engineer to raise the quota.
`insufficient_sub_bin`	insufficient available cards for sub-bin	Create Card	The sub-BIN pool for this card product has no available card numbers left under your account. This is an inventory issue, not a request issue — provide your account ID and the card product / BIN to UQPAY OPS so they can replenish the pool. Retrying the same request will keep failing until the pool is topped up.
`card_expired_error`	card has expired	Reset Card PIN	The card is past its expiry date — PIN reset is no longer allowed. Issue a replacement card if needed.
`status_not_supported`	card status or activation status not supported by request	Reset Card PIN · Create PAN Token · Retrieve Sensitive Card Details	The card must be in an active, usable state for this operation. Check the card’s `status` with Retrieve Card and activate or unblock it first.
`virtual_card_pin_error`	virtual cards do not allow pin settings	Reset Card PIN	Virtual cards do not have a PIN — call this endpoint only for physical cards.
`auto_cancel_trigger cannot be empty`	(the `code` string is itself the message — no separate `message` is sent)	Create Card	Provide `auto_cancel_trigger` when the card product requires it (typically one-time cards).
`invalid auto_cancel_trigger`	(the `code` string is itself the message)	Create Card	Use one of the allowed `auto_cancel_trigger` values documented on Create Card.
`expiry_at cannot be empty`	(the `code` string is itself the message)	Create Card	Provide `expiry_at` when the card product requires an explicit expiry date.
`invalid expiry_at`	(the `code` string is itself the message)	Create Card	Send `expiry_at` as a future ISO 8601 timestamp within the product’s maximum allowed lifetime.
`product_not_found`	product not found or inactive	Create Card	Verify `card_product_id` refers to a product enabled on your account. Use your UQPAY dashboard or contact your solutions engineer to confirm.
`account_balance_error`	insufficient balance or currency balance unavailable	Create Card	Fund your issuing balance in the card’s currency before retrying. See the Fund your issuing balance guide.
`card_art_not_available`	card_art_id is not available for this account	Create Card · Update Card · Set Default Card Art	The `card_art_id` you sent is not in this account’s available list. Call List Card Arts first to see allowed values, or omit `card_art_id` to use the account’s default card art.
`card_art_not_configured`	card art is not configured	Create Card · Update Card · List Card Arts	The channel has no system-default card art configured and the issuing account has no card art bound. Contact your UQPAY solutions engineer to configure card art for the channel.
`card_art_not_supported`	card_art_id is not supported for this product	Create Card · Update Card	The card product you selected does not support card art selection. Omit `card_art_id` from the request, or use a card product that supports card art.

Envelope B

`code`	Message	Typical endpoints	What to do
`400`	Card does not exists	Any endpoint that takes `{card_id}`	Verify the `card_id` exists under your account. Use List Cards to confirm.
`400`	card bin not config	Create Card · Assign Card	This BIN is not configured on your account, so cards cannot be created or assigned against it. Provide your account ID and the target BIN to UQPAY OPS to enable it.
`400`	card number not exist	Assign Card	The `card_number` is not in the available pool for your account. Verify: (1) the card number was provided to you by UQPAY for this account; (2) the digit length is correct — no spaces, no leading/trailing characters, no missing digits; (3) the card has not already been assigned to another cardholder.
`400`	Create card error	Create Card	Retry the request with the same `Idempotency-Key`. If it persists, double-check the request body against the Create Card schema and contact your UQPAY solutions engineer.
`400`	Update card error	Update Card · Activate Card	Retry the request. If the failure persists, verify the card is in an updatable state via Retrieve Card and that the fields you are changing are allowed for that product.
`400`	Card retrieve error	Retrieve Card · Retrieve Sensitive Card Details	Retry after a short backoff. If the card was recently created, wait a few seconds for propagation.
`400`	Card status is invalid	Update Card Status	Set `status` to one of the values allowed for the card’s current state (see Card lifecycle guide). You cannot move a cancelled card back to active, for example.
`400`	The card is failed.	Retrieve Card	The card provisioning failed at the issuer — it cannot be retrieved or used. Create a replacement card.
`400`	The card is not active.	Update Card · Card Recharge · Card Withdraw	Activate the card via Activate Card before updating it, recharging, or withdrawing funds.
`400`	Update reason is too long	Update Card Status	Shorten the `reason` field. It is stored in a bounded column — keep it under a few hundred characters.
`400`	The card has expired	Update Card · Update Card Status · Activate Card	The card is past `expiry_at` and can no longer be modified or activated. Issue a replacement card.
`400`	Invalid expiry date	Card Recharge · Card Withdraw	The card has expired — recharge and withdraw are blocked. Issue a replacement if the cardholder still needs funds.
`400`	Card holder not exists or is illegal	Create Card · Retrieve Card	Verify `cardholder_id` exists under your account via List Cardholders and is in an active state.
`400`	Cardholder not found or deactivated	List Cards	Confirm the `cardholder_id` filter points at an active cardholder under your account.
`400`	Invalid card type.	Create Card	Set `card_type` to `VIRTUAL` or `PHYSICAL` as supported by your card product.
`400`	Card currency is not support	Create Card	Use a `currency` that the selected card product allows. Check supported currencies with your UQPAY solutions engineer.
`400`	Card limit is illegal	Create Card	Set `spending_controls.spending_limit` to a positive integer in minor units, within the product’s allowed range.
`400`	Update card limit is less than the amount of used card	Update Card	The new limit must be at least equal to the card’s current utilized amount. Check `available_balance` / `used_amount` via Retrieve Card and raise the limit accordingly.
`400`	Failed Update. Card Limit should be greater than 0	Update Card	Set `spending_controls.spending_limit` to a value greater than `0`.
`400`	Failed Update. Card Limit should be greater than Per transaction	Update Card	The overall `spending_limit` must be greater than or equal to the per-transaction limit — raise the spending limit or lower the per-transaction cap.
`400`	Failed Update. Your transaction limit should be greater than 0	Update Card	Set the per-transaction limit to a value greater than `0`.
`400`	The single card not support changing card limits	Update Card	One-time cards have a fixed limit set at creation — the limit cannot be changed afterwards.
`400`	This operation cannot be performed on One-Time Card.	Update Card · Card Recharge · Card Withdraw	One-time cards cannot be updated, recharged, or withdrawn. Issue a new card if additional funds are needed.
`400`	Card recharge is error	Card Recharge	Retry the request with the same `Idempotency-Key`. If it persists, confirm the card’s status, currency, and your issuing balance.
`400`	Card withdraw not support	Card Withdraw	The card product does not support withdrawal. Use Update Card Status to cancel the card and recover the balance instead.
`400`	Card available limit insufficient	Card Withdraw	The withdrawal amount exceeds the card’s available balance. Retrieve the card’s current balance with Retrieve Card and lower `amount`.
`400`	Recharge amount is invalid	Card Recharge	Send `amount` as a positive integer in the card’s minor units (e.g. cents). Check precision matches the card currency.
`400`	Withdraw amount is invalid	Card Withdraw	Send `amount` as a positive integer in the card’s minor units that does not exceed the current card balance.
`400`	The card product currently does not support creation	Create Card	The card product is not enabled for new card creation. Contact your UQPAY solutions engineer to enable issuance.
`400`	The card currently does not support withdraw	Card Withdraw	Withdrawal is disabled for this card product. Cancel the card via Update Card Status to reclaim the balance.
`400`	The card currently does not support recharge	Card Recharge	Recharge is disabled for this card product (e.g. one-time cards). Issue a new card if additional funds are needed.
`400`	The card currently does not support cancel	Update Card Status	The card’s current status cannot be transitioned to cancelled (e.g. already cancelled, or pending). Retrieve the card to inspect its status first.
`400`	The card has been activated.	Activate Card	The card is already active — no further activation needed. Use Retrieve Card to confirm its state.
`400`	Invalid activation code.	Activate Card	Confirm `activation_code` matches the code printed on the physical card carrier. Codes are single-use per attempt.
`400`	Card order is not exists	Retrieve Card Order	Verify the `order_id` is correct and was returned from a previous card creation call.
`400`	Card product is error	Create Card · Activate Card	The `card_product_id` is misconfigured. Confirm the product is enabled for your account with your UQPAY solutions engineer.
`400`	Not found card products	Create Card · Update Card · Card Recharge · Card Withdraw	No matching card product is enabled for your account — contact your UQPAY solutions engineer to enable the product.
`400`	Product not opened	Card Recharge	The card product is not enabled for recharge. Contact your UQPAY solutions engineer.
`400`	Account card quota exceeded.	Create Card · Assign Card	Your account-wide active-card limit is reached. Cancel unused cards via Update Card Status or request a higher quota from your UQPAY solutions engineer.
`400`	Cardholder card quota exceeded.	Create Card · Assign Card	This cardholder has hit the maximum number of active cards. Cancel one of their cards or use a different cardholder.
`400`	Account balance not exists	Create Card · Card Recharge · Card Withdraw	Your account does not hold a balance in the card’s currency. Fund the issuing balance first — see Fund your issuing balance.
`400`	Insufficient balance	Create Card · Card Recharge · Card Withdraw	Top up your issuing balance in the card’s currency before retrying.
`400`	Spending controls is error	Update Card	The `spending_controls` payload failed validation — check `spending_limit`, `per_transaction_limit`, and any allow/block-list fields against Update Card schema.
`400`	Metadata is invalid	Update Card	`metadata` must be a flat `string → string` map. Remove nested objects and ensure keys and values are within size limits.
`400`	risk control setting is not allowed	Update Card	The `risk_controls` combination is not permitted for this card product. See the Card products capability matrix for allowed settings.
`400`	Exceed restrict max authorization amount	Create Card	The requested limit exceeds the product’s maximum authorization amount. Lower `spending_limit` or ask your UQPAY solutions engineer to raise the product ceiling.
`400`	Restrict config error	Update Card	The update violates the card product’s restriction configuration — verify any category, currency, or MCC allow-lists you are setting.
`400`	Not found product restrict	Update Card · Card Recharge · Card Withdraw	The card product’s restriction config is missing on the platform. Contact your UQPAY solutions engineer.
`400`	Convert data error	Create Card · Update Card	Internal data conversion failed — retry with the same `Idempotency-Key`. If it persists, report the request ID to your UQPAY solutions engineer.
`400`	Content type is not supported, please upload the correct format	Create Card	Send the request with `Content-Type: application/json`.
`400`	no pin payment amount failed.	Update Card · Activate Card	The `no_pin_payment_amount` you supplied failed validation. Confirm the value, precision, and currency match the card product’s configuration.
`400`	Negative no pin payment amount.	Activate Card	Send `no_pin_payment_amount` as a non-negative integer.
`400`	Invalid no pin payment amount precision.	Activate Card	Match the precision to the card currency’s minor units (e.g. 2 decimals for USD, 0 for JPY). Send the value as an integer in minor units.
`400`	invalid no pin payment amount for the current currency.	Update Card · Activate Card	The value exceeds the allowed ceiling for the card’s currency. Lower `no_pin_payment_amount` or check product configuration.
`400`	The no_pin_payment_amount restrict configuration cannot be found	Update Card · Activate Card	This card product does not support a no-PIN payment limit — omit the field from the request.
`429`	Request is too frequent	Create PAN Token · Retrieve Sensitive Card Details	Back off and retry with exponential delay. These endpoints are per-card rate-limited; do not poll tightly in loops.

Cardholder errors

Endpoints

Create Cardholder · List Cardholders · Update Cardholder · Retrieve Cardholder · Create Card (one-time issuance path)

type: cardholder_error Envelope A

`code`	Message	Typical endpoints	What to do
`cardholder_not_found`	cardholder not found or deactivated	Any endpoint that takes `{cardholder_id}` · Create Card	Verify the `cardholder_id` exists under your account via List Cardholders and is in an active state.
`cardholder_already_exists`	cardholder already exists	Create Card	A cardholder with the same identifying details is already on file — reuse that cardholder’s `cardholder_id` instead of creating a new one.
`email_duplicated`	email already used by another cardholder under account	Create Cardholder · Create Card	Provide a different `email` or reuse the existing cardholder record — look it up via List Cardholders.
`phone_number_duplicated`	phone number used by another cardholder under account	Create Cardholder · Create Card	Provide a different phone number or reuse the existing cardholder record — look it up via List Cardholders.
`invalid_phone_number`	invalid phone number or country code	Create Cardholder · Update Cardholder · Create Card	Send `phone.country_code` as an ISO digits-only country calling code and `phone.number` as digits-only in E.164 national form.
`invalid_first_name`	invalid first name, only letters and spaces allowed, no leading or trailing spaces	Create Cardholder · Create Card	Use only ASCII letters and spaces in `first_name`. Strip leading/trailing whitespace and remove punctuation or digits.
`invalid_last_name`	invalid last name, only letters and spaces allowed, no leading or trailing spaces	Create Cardholder · Create Card	Use only ASCII letters and spaces in `last_name`. Strip leading/trailing whitespace and remove punctuation or digits.
`invalid_date_of_birth`	cardholder under 18 or invalid date of birth format	Create Cardholder · Update Cardholder	Cardholders must be at least 18. Send `date_of_birth` as `YYYY-MM-DD`.
`missing_date_of_birth`	missing legal date of birth for document upload	Create Cardholder · Update Cardholder · Create Card	Include `date_of_birth` whenever you upload identity documents — the document check needs it.
`invalid_delivery_address`	invalid delivery address	Create Cardholder · Update Cardholder · Create Card	Populate every required subfield of the delivery address: `country`, `state`, `city`, `postal_code`, `line1`. Use ISO country codes.
`missing_country_code`	country_code is required for SUMSUB_REDIRECT KYC verification	Create Cardholder · Update Cardholder · Create Card	When `kyc_method` is `SUMSUB_REDIRECT`, include the cardholder’s residence `country_code` (ISO 3166-1 alpha-2).
`document_duplicated`	document already successfully reviewed	Update Cardholder	This identity document is already approved on the cardholder — do not re-upload it.
`file_type_not_supported`	unsupported document file type	Create Cardholder · Update Cardholder · Create Card	Upload the document as JPEG, PNG, or PDF.
`invalid_file_content`	invalid base64 encoded document content	Create Cardholder · Update Cardholder · Create Card	Ensure the file bytes are standard Base64-encoded (no data-URL prefix, no line breaks) before sending.
`document_size_exceeded`	document size exceeds 2MB limit	Create Cardholder · Update Cardholder · Create Card	Compress or re-scan the document so the decoded file is under 2 MB.
`document_review_required`	cardholder’s document requires review	Create Card	The cardholder’s document is still in manual review. Wait for the `cardholder.kyc_status` webhook or poll Retrieve Cardholder until KYC is approved.
`identity_file_missing`	required identity file is missing	Create Cardholder · Update Cardholder · Create Card	Upload the expected identity document (e.g. both front and back of an ID card) in the `identity_documents` payload.
`invalid_identity_type`	invalid identity type, must be ID_CARD or PASSPORT	Create Cardholder · Update Cardholder · Create Card	Set `identity_type` to `ID_CARD` or `PASSPORT`.
`invalid_kyc_method`	invalid KYC verification method, must be THIRD_PARTY or SUMSUB_REDIRECT	Create Cardholder · Update Cardholder · Create Card	Set `kyc_method` to `THIRD_PARTY` or `SUMSUB_REDIRECT`.
`kyc_proof_required`	kyc_proof is required when method is THIRD_PARTY	Create Cardholder · Update Cardholder · Create Card	Include a `kyc_proof` payload describing your own KYC provider’s check when `kyc_method` is `THIRD_PARTY`.
`reference_id_duplicated`	reference_id already used by another cardholder	Create Cardholder · Update Cardholder · Create Card	Supply a unique `reference_id` — another cardholder on this account already uses the one you sent.
`reference_id_too_short`	reference_id must be at least 10 characters long	Create Cardholder · Update Cardholder · Create Card	Use a `reference_id` of 10 characters or more.
`cardholder_kyc_pending`	cardholder KYC is under review, cannot proceed	Create Card	Wait for KYC to complete. Poll Retrieve Cardholder or listen for the `cardholder.kyc_status` webhook before retrying.
`cardholder_kyc_failed`	cardholder KYC has been rejected	Create Card	Ask the cardholder to resubmit identity documents or create a new cardholder record. Contact your UQPAY solutions engineer if the rejection reason is unclear.
`kyc_insufficient`	cardholder information does not meet this product’s requirements (response includes `missing_fields`)	Create Card	Update the cardholder with the fields listed in the response’s `missing_fields` array via Update Cardholder, then retry.
`supplement_fields_incomplete`	supplemented cardholder fields are incomplete (response includes `missing_fields`)	Create Card	Provide every field listed in the response’s `missing_fields` inside `cardholder_required_fields` on the retry.
`cardholder_cannot_update_during_review`	cannot update KYC fields while review is pending	Update Cardholder	Wait for KYC review to finish before editing identity or address fields. Non-KYC fields (e.g. `metadata`) can still be updated.
`bin_required_fields_not_configured`	required_fields not configured for this card BIN, cannot proceed with card creation	Create Card	The card BIN’s required-fields configuration is missing on the platform. Contact your UQPAY solutions engineer.
`cardholder_missing_info`	either cardholder_id or complete cardholder_required_fields must be provided	Create Card	Send either `cardholder_id` for an existing cardholder, or `cardholder_required_fields` with the full one-time issuance payload.
`cardholder_incomplete_fields`	cardholder_required_fields is incomplete for one-time card issuance (response includes `missing_fields`)	Create Card	Add every field from the response’s `missing_fields` to `cardholder_required_fields` and retry.

Balance errors

Endpoints

Retrieve Issuing Balance · List Issuing Balances · List Issuing Balances Transactions

type: account_error Envelope A

`code`	Message	Typical endpoints	What to do
`account_balance_error`	insufficient balance or currency balance unavailable	Retrieve Issuing Balance · List Issuing Balances · List Issuing Balances Transactions	Confirm your account holds a balance in the requested `currency`. Call List Issuing Balances to see all available currency balances.

Transaction errors

Endpoints

List Cards Transactions · Retrieve Cards Transaction · Claim Unsolicited Refund · Simulate Authorization · Simulate Reversal

Envelope A types: invalid_request_error (transaction not found / not under the connected account, or an unsolicited-refund claim that cannot be processed). Claim Unsolicited Refund returns Envelope A only — it has no Envelope B errors. Envelope A

`code`	Message	Typical endpoints	What to do
`invalid_request_error`	`transaction[<id>] not found under the connected account`	Retrieve Cards Transaction	Verify the `transaction_id` exists under your account. Use List Cards Transactions to find valid IDs.
`invalid_request_error`	original transaction not found or not owned by current account	Claim Unsolicited Refund	Confirm `related_transaction_id` is the original authorization’s `transaction_id` (not its `short_reference_id`) and that the transaction belongs to your account.
`invalid_request_error`	original transaction is not a valid authorization source transaction	Claim Unsolicited Refund	`related_transaction_id` must reference a successful authorization. Use Retrieve Cards Transaction to confirm the source transaction’s type and status.
`invalid_request_error`	no unreferenced refund intercept transaction found to claim	Claim Unsolicited Refund	There is no intercepted unsolicited refund waiting against this original transaction, so nothing can be released. No action is needed unless you expected a refund to have arrived.
`invalid_request_error`	a release request for this original transaction is already in progress	Claim Unsolicited Refund	A claim for this original transaction is already being processed. Do not resubmit — wait for the asynchronous result.
`invalid_request_error`	unsolicited refund claim only supported on VISA	Claim Unsolicited Refund	This claim is only available for Business Visa cards. The original transaction’s card is not a Business Visa, so it cannot be claimed.

Envelope B

`code`	Message	Typical endpoints	What to do
`400`	Card authorize transaction is error	Simulate Authorization	Retry the simulator call. If it persists, confirm the target card is active and the amount/currency match the card. This endpoint is sandbox-only.
`400`	Card reversal transaction is error	Simulate Reversal	Verify the `transaction_id` you are reversing exists and refers to a previously-simulated authorization. This endpoint is sandbox-only.
`400`	Invalid channel code	Simulate Authorization · Simulate Reversal	Set `channel` to a supported sandbox channel value. Ask your UQPAY solutions engineer for the allowed list.
`400`	MCC is error	Simulate Authorization	Provide a 4-digit numeric `mcc` code allowed for the card’s spending controls.
`400`	Account status error	Simulate Authorization · Simulate Reversal	The account cannot simulate authorizations in its current state. Confirm the account is active via your UQPAY dashboard.
`400`	Restrict config error	Simulate Authorization · Simulate Reversal	The simulated transaction violates the card’s spending controls (MCC, currency, country, or limit). Adjust the simulator request or the card’s `spending_controls`.

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

Error response formats

Error types

Common errors

Envelope A (string codes)

Envelope B (legacy flat 400)

Resource errors

Card errors

Cardholder errors

Balance errors

Transaction errors

​Error response formats

​Error types

​Common errors

​Envelope A (string codes)

​Envelope B (legacy flat 400)

​Resource errors

​Card errors

​Cardholder errors

​Balance errors

​Transaction errors

Error response formats

Error types

Common errors

Envelope A (string codes)

Envelope B (legacy flat 400)

Resource errors

Card errors

Cardholder errors

Balance errors

Transaction errors