> ## 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 Card Issuance API, where they appear, and what to do when you encounter them.
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.
Most card and cardholder errors return this envelope. `type` determines the HTTP status.
```json theme={null}
{
"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](#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.
```json theme={null}
{
"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
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](/card-issuance/v1.6/guide/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](/card-issuance/v1.6/guide/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
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
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
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[] 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`. |