错误码

当 Card Issuance API 调用失败时，网关会返回非 2xx 的 HTTP 状态码以及 JSON 错误体。通过本页你可以定位问题原因并恢复调用。

错误响应格式

Card Issuance API 使用两种响应信封。具体返回哪一种取决于处理请求的 handler。

信封 A —— 字符串 code
信封 B —— 旧版扁平 400

绝大多数卡片与持卡人错误都会返回这种信封。type 决定 HTTP 状态码。

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

Field	含义
`type`	高层分类。映射到 HTTP 状态码（见错误类型）。
`code`	机器可读的字符串标识。用于程序化处理。
`message`	人类可读的描述。可以安全写入日志，但不建议原样展示给终端用户。

一部分 handler——主要是早于类型化错误系统的老旧卡片操作——会返回一种扁平结构：code 是作为字符串的 HTTP 状态码，message 承载错误语句。

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

Field	含义
`code`	作为字符串的 HTTP 状态码（校验/业务错误为 `"400"`，限流请求为 `"429"`）。按 `message` 字段分支做细粒度处理。
`message`	人类可读的描述。

处理响应时，根据是否存在 type 字段来判断使用哪种信封。信封 B 永远不带 type。

错误类型

信封 A 把错误码按 type 分组，每个 type 固定映射到一个 HTTP 状态码。

`type`	HTTP	出现场景
`invalid_request_error`	400	请求校验失败。
`card_error`	400	违反卡资源规则。
`cardholder_error`	400	违反持卡人资源规则。
`account_error`	400	违反账户/产品/余额规则。
`idempotency_error`	400	幂等键重放或不匹配。
`unauthorized_error`	401 / 403	API 密钥缺失、无效或没有权限。401 时 `code` 为 `unauthorized_error`，403 时为 `forbidden`。
`api_error`	500	内部服务器错误。可以用相同的 `Idempotency-Key` 安全重试。

信封 B 不带 type 字段；通过 message 分支区分具体情况。

通用错误

以下错误可能出现在任何需要鉴权的 endpoint。

信封 A（字符串 code）

`code`	`type`	错误消息	处理方式
`invalid_request_error`	`invalid_request_error`	（视场景而定——`message` 中会指出字段路径和校验规则）	TODO
`unauthorized_error`	`unauthorized_error`	Token expired, IP not allowed, or access token dependencies unavailable	通过 Access Token 获取新的 Access Token，确认调用方 IP 在白名单内，然后用新的 `x-auth-token` 头重试。
`forbidden`	`unauthorized_error`	Returned when the API key lacks permission (currently guards `GET /cards/{id}/secure`)	联系你的 UQPAY solutions engineer 为 API 密钥开启敏感卡详情权限，然后重试。
`api_error`	`api_error`	（视场景而定——通用的内部服务器错误）	TODO
`account_not_found`	`account_error`	account not found or deactivated	确认你使用的 `client_id` / API 密钥归属于一个生效中的 UQPAY 账户。如果账户是近期创建的，请确认入驻流程已完成。
`sub_account_not_found`	`account_error`	sub-account associated with the on-behalf-of not found or deactivated	确认 `on-behalf-of` 头指向你主账户下一个存在且生效的子账户，或不带该头以主账户身份调用。
`user_not_found`	`account_error`	user associated with account not found or deactivated	确认绑定到 API 密钥的用户仍在生效。如果该用户近期被禁用，请联系你的 UQPAY solutions engineer。
`request_being_processed`	`idempotency_error`	request is being processed	稍后用相同的 `Idempotency-Key` 重试——原始请求仍在处理中。重试之间不要修改请求体。
`invalid_key_format`	`idempotency_error`	invalid idempotency key format	提供一个非空、长度不超过 255 个字符的 `Idempotency-Key` 头（推荐使用 UUID v4）。
`key_mismatch_account`	`idempotency_error`	key does not belong to account	该 `Idempotency-Key` 之前被其他账户使用过——请为当前账户生成一个新的 key。
`key_mismatch_api`	`idempotency_error`	api associated with key is not the original	`Idempotency-Key` 只能在首次使用时的同一 endpoint + method 上重用。换 endpoint 请生成新的 key。

信封 B（旧版扁平 400）

`code`	错误消息	处理方式
`400`	Request parameters invalid	对照 API Reference 中该 endpoint 的 schema，检查每个必填字段是否存在且类型正确。
`400`	Params JSON error	请求体 JSON 解析失败——检查是否有尾随逗号、未转义的引号，或缺少 `Content-Type: application/json` 头。
`400`	Account does not exist.	确认 API 密钥归属于一个生效中的账户，且解析到的账户未被停用。
`400`	An internal error occurred, please try again	短暂回退后用相同的 `Idempotency-Key` 重试。如果错误持续，联系你的 UQPAY solutions engineer 并附上请求时间戳。
`400`	Login expired	通过 Access Token 获取新的 Access Token，并用新的 `x-auth-token` 重试。
`429`	Request is too frequent	按指数退避重试。敏感卡和 PAN Token 类 endpoint 按卡限流——轮询间隔请不要短于几秒。

资源错误

卡片错误

相关 endpoint

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

信封 A 的 type：card_error，以及创建卡片时可能出现的 account_error（product_not_found、account_balance_error）。 信封 A

`code`	错误消息	典型接口	处理方式
`card_not_found`	card not found or deactivated	任何接收 `{card_id}` 的 endpoint	确认 `card_id` 存在于你的账户下且未注销。使用 List Cards 或 Retrieve Card 核对。
`operation_not_authorized`	requested card operation type is not authorized	Create Card	你的账户没有发行该卡类型的权限——联系你的 UQPAY solutions engineer 在账户上开启。
`risk_control_not_allowed`	risk control setting is not allowed	Create Card	移除或调整超出卡产品允许范围的 `risk_controls` 条目。支持的配置见卡产品能力矩阵。
`currency_not_allowed`	card currency is not allowed	Create Card	将 `currency` 设置为所选卡产品支持的币种之一。找你的 UQPAY solutions engineer 确认产品配置。
`limit_out_of_range`	card limit is either less than minimum card limit or greater than maximum card limit	Create Card	将 `spending_controls.spending_limit` 设置在该产品配置的最小值与最大值之间。上下限按卡产品设定——联系你的 UQPAY solutions engineer 确认。
`cardholder_quota_exceeded`	card quota of cardholder exceeds limit	Create Card	该持卡人已达到允许的最大活动卡数量。先通过 Update Card Status 注销一张已有的卡，再发行新卡，或换一个持卡人。
`account_quota_exceeded`	card quota of account exceeds limit	Create Card	账户级别的卡数量上限已达到。通过 Update Card Status 注销未使用的卡，或联系你的 UQPAY solutions engineer 提高配额。
`insufficient_sub_bin`	insufficient available cards for sub-bin	Create Card	你账户下该卡产品对应的子 BIN 池已无可用卡号。这是库存问题，不是请求问题——请将你的账户 ID 以及目标卡产品 / BIN 提供给 UQPAY OPS，由 OPS 补充库存。在库存补齐之前，相同请求重试也会一直失败。
`card_expired_error`	card has expired	Reset Card PIN	卡已过期——不再允许重置 PIN 码。如有需要，请补发一张新卡。
`status_not_supported`	card status or activation status not supported by request	Reset Card PIN · Create PAN Token · Retrieve Sensitive Card Details	执行该操作要求卡处于可用的激活状态。用 Retrieve Card 查看 `status`，先激活或解除锁定。
`virtual_card_pin_error`	virtual cards do not allow pin settings	Reset Card PIN	虚拟卡没有 PIN 码——该 endpoint 仅适用于实体卡。
`auto_cancel_trigger cannot be empty`	（`code` 字符串即 message——不单独返回 `message`）	Create Card	当卡产品要求时（通常是一次性卡），需要提供 `auto_cancel_trigger`。
`invalid auto_cancel_trigger`	（`code` 字符串即 message）	Create Card	使用 Create Card 文档中列出的合法 `auto_cancel_trigger` 取值之一。
`expiry_at cannot be empty`	（`code` 字符串即 message）	Create Card	当卡产品要求显式指定过期日期时，需要提供 `expiry_at`。
`invalid expiry_at`	（`code` 字符串即 message）	Create Card	`expiry_at` 必须是 ISO 8601 格式的未来时间戳，且在产品允许的最长有效期内。
`product_not_found`	product not found or inactive	Create Card	确认 `card_product_id` 指向一个在你的账户上启用的产品。通过 UQPAY 控制台或联系 solutions engineer 核对。
`account_balance_error`	insufficient balance or currency balance unavailable	Create Card	在重试之前，为卡币种对应的发卡账户余额充值。参见 Fund your issuing balance 指南。
`card_art_not_available`	card_art_id is not available for this account	Create Card · Update Card · Set Default Card Art	你传入的 `card_art_id` 不在该账户的可用列表中。先调用 List Card Arts 查看允许的取值，或省略 `card_art_id` 改用账户的默认卡面。
`card_art_not_configured`	card art is not configured	Create Card · Update Card · List Card Arts	通道没有配置系统默认卡面，发卡账户也没有绑定任何卡面。联系你的 UQPAY solutions engineer 为该通道配置卡面。
`card_art_not_supported`	card_art_id is not supported for this product	Create Card · Update Card	所选卡产品不支持卡面选择。请从请求中省略 `card_art_id`，或改用支持卡面的卡产品。

信封 B

`code`	错误消息	典型接口	处理方式
`400`	Card does not exists	任何接收 `{card_id}` 的 endpoint	确认 `card_id` 存在于你的账户下。使用 List Cards 核对。
`400`	card bin not config	Create Card · Assign Card	你账户下尚未配置该 BIN，因此无法在该 BIN 上创建或分配卡片。请将你的账户 ID 以及目标 BIN 提供给 UQPAY OPS，由 OPS 配置后即可使用。
`400`	card number not exist	Assign Card	该 `card_number` 不在你账户当前的可用卡池中。请核对：(1) 卡号是 UQPAY 为该账户提供的；(2) 卡号长度正确——不要带空格、不要带前后多余字符、不要少位；(3) 该卡片尚未被分配给其他持卡人。
`400`	Create card error	Create Card	用相同的 `Idempotency-Key` 重试。如果持续失败，对照 Create Card 的 schema 检查请求体，并联系你的 UQPAY solutions engineer。
`400`	Update card error	Update Card · Activate Card	重试请求。如果仍然失败，通过 Retrieve Card 确认卡处于可更新状态，且要修改的字段在该产品下允许修改。
`400`	Card retrieve error	Retrieve Card · Retrieve Sensitive Card Details	短暂回退后重试。如果卡是近期创建的，请等几秒钟让数据同步。
`400`	Card status is invalid	Update Card Status	将 `status` 设为卡当前状态允许的取值之一（见 Card lifecycle 指南）。例如，已注销的卡无法再切回 active 状态。
`400`	The card is failed.	Retrieve Card	卡在发卡方侧制卡失败——既无法查询也无法使用。请补发一张新卡。
`400`	The card is not active.	Update Card · Card Recharge · Card Withdraw	在更新、充值或提现之前，先通过 Activate Card 激活卡片。
`400`	Update reason is too long	Update Card Status	缩短 `reason` 字段的内容。该字段以有限长度的列存储——请控制在几百个字符以内。
`400`	The card has expired	Update Card · Update Card Status · Activate Card	卡已超过 `expiry_at`，无法再修改或激活。请补发一张新卡。
`400`	Invalid expiry date	Card Recharge · Card Withdraw	卡已过期——充值和提现被阻断。如持卡人仍需用卡，请补发新卡。
`400`	Card holder not exists or is illegal	Create Card · Retrieve Card	通过 List Cardholders 确认 `cardholder_id` 存在于你的账户下且处于生效状态。
`400`	Cardholder not found or deactivated	List Cards	确认 `cardholder_id` 过滤条件指向一个在你账户下、处于生效状态的持卡人。
`400`	Invalid card type.	Create Card	根据卡产品支持的形态，将 `card_type` 设置为 `VIRTUAL` 或 `PHYSICAL`。
`400`	Card currency is not support	Create Card	使用所选卡产品允许的 `currency`。可向你的 UQPAY solutions engineer 确认支持的币种。
`400`	Card limit is illegal	Create Card	将 `spending_controls.spending_limit` 设置为以最小货币单位表示的正整数，且在产品允许的区间内。
`400`	Update card limit is less than the amount of used card	Update Card	新限额必须不低于卡当前已使用的金额。通过 Retrieve Card 查看 `available_balance` / `used_amount`，并据此提高限额。
`400`	Failed Update. Card Limit should be greater than 0	Update Card	将 `spending_controls.spending_limit` 设置为大于 `0` 的值。
`400`	Failed Update. Card Limit should be greater than Per transaction	Update Card	总的 `spending_limit` 必须大于或等于单笔限额——请提高消费限额或降低单笔上限。
`400`	Failed Update. Your transaction limit should be greater than 0	Update Card	将单笔限额设置为大于 `0` 的值。
`400`	The single card not support changing card limits	Update Card	一次性卡在创建时已固定限额——创建后不可更改。
`400`	This operation cannot be performed on One-Time Card.	Update Card · Card Recharge · Card Withdraw	一次性卡不支持更新、充值或提现。如需追加资金，请发行一张新卡。
`400`	Card recharge is error	Card Recharge	用相同的 `Idempotency-Key` 重试。如果持续失败，确认卡的状态、币种以及你的发卡账户余额。
`400`	Card withdraw not support	Card Withdraw	该卡产品不支持提现。改用 Update Card Status 注销卡片以收回余额。
`400`	Card available limit insufficient	Card Withdraw	提现金额超过卡的可用余额。通过 Retrieve Card 查看当前余额，并降低 `amount`。
`400`	Recharge amount is invalid	Card Recharge	`amount` 必须是以卡币种最小单位（如分）表示的正整数。确认精度与卡币种一致。
`400`	Withdraw amount is invalid	Card Withdraw	`amount` 必须是以卡币种最小单位表示的正整数，且不超过当前卡余额。
`400`	The card product currently does not support creation	Create Card	该卡产品未开放新卡创建。联系你的 UQPAY solutions engineer 启用发卡能力。
`400`	The card currently does not support withdraw	Card Withdraw	该卡产品禁用了提现。通过 Update Card Status 注销卡片以回收余额。
`400`	The card currently does not support recharge	Card Recharge	该卡产品禁用了充值（例如一次性卡）。如需追加资金，请发行新卡。
`400`	The card currently does not support cancel	Update Card Status	卡当前状态不能转到已注销（例如已注销或待处理）。请先查询卡查看其状态。
`400`	The card has been activated.	Activate Card	卡已处于激活状态——无需再次激活。用 Retrieve Card 确认状态。
`400`	Invalid activation code.	Activate Card	确认 `activation_code` 与实体卡卡封上的激活码一致。激活码每次尝试只能使用一次。
`400`	Card order is not exists	Retrieve Card Order	确认 `order_id` 正确，且来自此前某次创建卡的响应。
`400`	Card product is error	Create Card · Activate Card	`card_product_id` 配置有误。联系你的 UQPAY solutions engineer 确认该产品已在你的账户上启用。
`400`	Not found card products	Create Card · Update Card · Card Recharge · Card Withdraw	你的账户下没有匹配的可用卡产品——联系你的 UQPAY solutions engineer 启用该产品。
`400`	Product not opened	Card Recharge	该卡产品未开放充值。联系你的 UQPAY solutions engineer。
`400`	Account card quota exceeded.	Create Card · Assign Card	账户级别的活动卡上限已达到。通过 Update Card Status 注销未使用的卡，或向你的 UQPAY solutions engineer 申请提高配额。
`400`	Cardholder card quota exceeded.	Create Card · Assign Card	该持卡人已达到最大活动卡数量。注销其中一张卡，或改用其他持卡人。
`400`	Account balance not exists	Create Card · Card Recharge · Card Withdraw	你的账户不持有卡币种对应的余额。请先为发卡账户余额充值——参见 Fund your issuing balance。
`400`	Insufficient balance	Create Card · Card Recharge · Card Withdraw	在重试之前，为卡币种对应的发卡账户余额充值。
`400`	Spending controls is error	Update Card	`spending_controls` 载荷校验失败——对照 Update Card 的 schema 检查 `spending_limit`、`per_transaction_limit` 以及任何白/黑名单字段。
`400`	Metadata is invalid	Update Card	`metadata` 必须是扁平的 `string → string` 映射。移除嵌套对象，并确保键和值在长度限制内。
`400`	risk control setting is not allowed	Update Card	该 `risk_controls` 组合在此卡产品下不被允许。支持的配置见卡产品能力矩阵。
`400`	Exceed restrict max authorization amount	Create Card	请求的限额超过了产品允许的最大授权金额。降低 `spending_limit`，或请你的 UQPAY solutions engineer 提高产品上限。
`400`	Restrict config error	Update Card	本次更新违反了卡产品的限制配置——请核对你正在设置的类别、币种或 MCC 白名单。
`400`	Not found product restrict	Update Card · Card Recharge · Card Withdraw	平台上缺少该卡产品的限制配置。联系你的 UQPAY solutions engineer。
`400`	Convert data error	Create Card · Update Card	内部数据转换失败——用相同的 `Idempotency-Key` 重试。如果持续失败，请把请求 ID 报给你的 UQPAY solutions engineer。
`400`	Content type is not supported, please upload the correct format	Create Card	使用 `Content-Type: application/json` 发送请求。
`400`	no pin payment amount failed.	Update Card · Activate Card	你提供的 `no_pin_payment_amount` 校验失败。确认取值、精度和币种与卡产品配置一致。
`400`	Negative no pin payment amount.	Activate Card	`no_pin_payment_amount` 必须是非负整数。
`400`	Invalid no pin payment amount precision.	Activate Card	精度需与卡币种的最小单位一致（例如 USD 为 2 位小数，JPY 为 0 位）。以最小单位的整数发送。
`400`	invalid no pin payment amount for the current currency.	Update Card · Activate Card	数值超过了卡币种的允许上限。降低 `no_pin_payment_amount`，或检查产品配置。
`400`	The no_pin_payment_amount restrict configuration cannot be found	Update Card · Activate Card	该卡产品不支持免密金额上限——请从请求中移除该字段。
`429`	Request is too frequent	Create PAN Token · Retrieve Sensitive Card Details	按指数退避重试。这些 endpoint 按卡限流；不要在循环中紧密轮询。

持卡人错误

相关 endpoint

Create Cardholder · List Cardholders · Update Cardholder · Retrieve Cardholder · Create Card（一次性发卡路径）

type：cardholder_error 信封 A

`code`	错误消息	典型接口	处理方式
`cardholder_not_found`	cardholder not found or deactivated	任何接收 `{cardholder_id}` 的 endpoint · Create Card	通过 List Cardholders 确认 `cardholder_id` 存在于你的账户下且处于生效状态。
`cardholder_already_exists`	cardholder already exists	Create Card	系统中已存在具有相同身份信息的持卡人——请复用该持卡人的 `cardholder_id`，不要新建。
`email_duplicated`	email already used by another cardholder under account	Create Cardholder · Create Card	更换 `email`，或复用已有的持卡人记录——通过 List Cardholders 查询。
`phone_number_duplicated`	phone number used by another cardholder under account	Create Cardholder · Create Card	更换手机号，或复用已有的持卡人记录——通过 List Cardholders 查询。
`invalid_phone_number`	invalid phone number or country code	Create Cardholder · Update Cardholder · Create Card	`phone.country_code` 以纯数字的 ISO 国家电话代码填写，`phone.number` 以 E.164 国内格式的纯数字填写。
`invalid_first_name`	invalid first name, only letters and spaces allowed, no leading or trailing spaces	Create Cardholder · Create Card	`first_name` 仅允许 ASCII 字母和空格。去除首尾空格，并移除标点或数字。
`invalid_last_name`	invalid last name, only letters and spaces allowed, no leading or trailing spaces	Create Cardholder · Create Card	`last_name` 仅允许 ASCII 字母和空格。去除首尾空格，并移除标点或数字。
`invalid_date_of_birth`	cardholder under 18 or invalid date of birth format	Create Cardholder · Update Cardholder	持卡人必须年满 18 岁。`date_of_birth` 以 `YYYY-MM-DD` 格式发送。
`missing_date_of_birth`	missing legal date of birth for document upload	Create Cardholder · Update Cardholder · Create Card	上传身份证件时必须同时提供 `date_of_birth`——证件核验需要该字段。
`invalid_delivery_address`	invalid delivery address	Create Cardholder · Update Cardholder · Create Card	完整填写寄送地址的所有必填子字段：`country`、`state`、`city`、`postal_code`、`line1`。使用 ISO 国家代码。
`missing_country_code`	country_code is required for SUMSUB_REDIRECT KYC verification	Create Cardholder · Update Cardholder · Create Card	当 `kyc_method` 为 `SUMSUB_REDIRECT` 时，需要提供持卡人的居住地 `country_code`（ISO 3166-1 alpha-2）。
`document_duplicated`	document already successfully reviewed	Update Cardholder	该身份证件已在持卡人上通过审核——不要重复上传。
`file_type_not_supported`	unsupported document file type	Create Cardholder · Update Cardholder · Create Card	以 JPEG、PNG 或 PDF 格式上传证件。
`invalid_file_content`	invalid base64 encoded document content	Create Cardholder · Update Cardholder · Create Card	确认文件字节为标准 Base64 编码（不带 data-URL 前缀、不含换行）后再发送。
`document_size_exceeded`	document size exceeds 2MB limit	Create Cardholder · Update Cardholder · Create Card	压缩或重新扫描证件，确保解码后文件小于 2 MB。
`document_review_required`	cardholder’s document requires review	Create Card	该持卡人的证件仍在人工审核中。等待 `cardholder.kyc_status` Webhook，或轮询 Retrieve Cardholder 直到 KYC 通过。
`identity_file_missing`	required identity file is missing	Create Cardholder · Update Cardholder · Create Card	在 `identity_documents` 中上传所需的身份证件（例如身份证的正反两面）。
`invalid_identity_type`	invalid identity type, must be ID_CARD or PASSPORT	Create Cardholder · Update Cardholder · Create Card	将 `identity_type` 设置为 `ID_CARD` 或 `PASSPORT`。
`invalid_kyc_method`	invalid KYC verification method, must be THIRD_PARTY or SUMSUB_REDIRECT	Create Cardholder · Update Cardholder · Create Card	将 `kyc_method` 设置为 `THIRD_PARTY` 或 `SUMSUB_REDIRECT`。
`kyc_proof_required`	kyc_proof is required when method is THIRD_PARTY	Create Cardholder · Update Cardholder · Create Card	当 `kyc_method` 为 `THIRD_PARTY` 时，提供 `kyc_proof` 载荷以描述你方 KYC 服务商的核验结果。
`reference_id_duplicated`	reference_id already used by another cardholder	Create Cardholder · Update Cardholder · Create Card	提供唯一的 `reference_id`——该账户下已有其他持卡人使用了你发送的值。
`reference_id_too_short`	reference_id must be at least 10 characters long	Create Cardholder · Update Cardholder · Create Card	`reference_id` 长度至少为 10 个字符。
`cardholder_kyc_pending`	cardholder KYC is under review, cannot proceed	Create Card	等待 KYC 完成。轮询 Retrieve Cardholder 或监听 `cardholder.kyc_status` Webhook，然后再重试。
`cardholder_kyc_failed`	cardholder KYC has been rejected	Create Card	让持卡人重新提交身份证件，或新建一个持卡人记录。如果拒绝原因不明，联系你的 UQPAY solutions engineer。
`kyc_insufficient`	cardholder information does not meet this product’s requirements (response includes `missing_fields`)	Create Card	通过 Update Cardholder 补齐响应中 `missing_fields` 列出的字段，然后重试。
`supplement_fields_incomplete`	supplemented cardholder fields are incomplete (response includes `missing_fields`)	Create Card	在重试时，把响应 `missing_fields` 里的每个字段填入 `cardholder_required_fields`。
`cardholder_cannot_update_during_review`	cannot update KYC fields while review is pending	Update Cardholder	等待 KYC 审核结束，再编辑身份或地址字段。非 KYC 字段（如 `metadata`）仍可更新。
`bin_required_fields_not_configured`	required_fields not configured for this card BIN, cannot proceed with card creation	Create Card	该卡 BIN 的 required_fields 配置在平台上缺失。联系你的 UQPAY solutions engineer。
`cardholder_missing_info`	either cardholder_id or complete cardholder_required_fields must be provided	Create Card	要么提供已存在的 `cardholder_id`，要么在 `cardholder_required_fields` 中提供完整的一次性发卡载荷。
`cardholder_incomplete_fields`	cardholder_required_fields is incomplete for one-time card issuance (response includes `missing_fields`)	Create Card	把响应 `missing_fields` 中的每个字段补充到 `cardholder_required_fields`，再重试。

余额错误

相关 endpoint

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

type：account_error 信封 A

`code`	错误消息	典型接口	处理方式
`account_balance_error`	insufficient balance or currency balance unavailable	Retrieve Issuing Balance · List Issuing Balances · List Issuing Balances Transactions	确认你的账户持有请求 `currency` 对应的余额。调用 List Issuing Balances 查看所有可用币种余额。

交易错误

相关 endpoint

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

信封 A 的 type：invalid_request_error（交易不存在 / 不属于当前关联账户，或无源退款认领无法处理）。Claim Unsolicited Refund 仅返回信封 A，没有信封 B 错误。 信封 A

`code`	错误消息	典型接口	处理方式
`invalid_request_error`	`transaction[<id>] not found under the connected account`	Retrieve Cards Transaction	确认 `transaction_id` 存在于你的账户下。使用 List Cards Transactions 查找可用的 ID。
`invalid_request_error`	original transaction not found or not owned by current account	Claim Unsolicited Refund	确认 `related_transaction_id` 是原授权交易的 `transaction_id`（不是它的 `short_reference_id`），且该交易属于你的账户。
`invalid_request_error`	original transaction is not a valid authorization source transaction	Claim Unsolicited Refund	`related_transaction_id` 必须指向一笔成功的授权交易。用 Retrieve Cards Transaction 确认源交易的类型与状态。
`invalid_request_error`	no unreferenced refund intercept transaction found to claim	Claim Unsolicited Refund	该原交易下没有等待认领的被拦截无源退款，无可释放。除非你确实预期有退款到账，否则无需处理。
`invalid_request_error`	a release request for this original transaction is already in progress	Claim Unsolicited Refund	该原交易已有认领申请在处理中。请勿重复提交，等待异步结果。
`invalid_request_error`	unsolicited refund claim only supported on VISA	Claim Unsolicited Refund	该认领仅支持 Business Visa 卡。原交易的卡不是 Business Visa，无法认领。

信封 B

`code`	错误消息	典型接口	处理方式
`400`	Card authorize transaction is error	Simulate Authorization	重试模拟器调用。如果持续失败，确认目标卡处于激活状态，且金额/币种与该卡匹配。此 endpoint 仅沙盒可用。
`400`	Card reversal transaction is error	Simulate Reversal	确认要冲正的 `transaction_id` 存在，且指向此前某次模拟过的授权。此 endpoint 仅沙盒可用。
`400`	Invalid channel code	Simulate Authorization · Simulate Reversal	将 `channel` 设置为支持的沙盒渠道值。可向你的 UQPAY solutions engineer 获取允许列表。
`400`	MCC is error	Simulate Authorization	提供该卡消费限额允许的 4 位数字 `mcc` 代码。
`400`	Account status error	Simulate Authorization · Simulate Reversal	账户当前状态无法模拟授权。通过 UQPAY 控制台确认账户处于生效状态。
`400`	Restrict config error	Simulate Authorization · Simulate Reversal	模拟交易违反了卡的消费限额（MCC、币种、国家或限额）。调整模拟器请求或卡的 `spending_controls`。

入门

持卡人

卡片

充值

管理与安全

集成

参考

错误响应格式

错误类型

通用错误

信封 A（字符串 code）

信封 B（旧版扁平 400）

资源错误

卡片错误

持卡人错误

余额错误

交易错误

​错误响应格式

​错误类型

​通用错误

​信封 A（字符串 code）

​信封 B（旧版扁平 400）

​资源错误

​卡片错误

​持卡人错误

​余额错误

​交易错误

错误响应格式

错误类型

通用错误

信封 A（字符串 code）

信封 B（旧版扁平 400）

资源错误

卡片错误

持卡人错误

余额错误

交易错误