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.

Envelope A — string code

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.

Envelope B — legacy flat 400

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 Supported BINs for risk control configurations guide.
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.

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 Supported BINs for risk control configurations 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 · Simulate Authorization · Simulate Reversal

Envelope A types: invalid_request_error (transaction not found / not under the connected account).

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.

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.