错误 - CBPay

所有错误都采用相同的结构：

{
  "error": "insufficient_funds",
  "message": "account balance is not enough for this operation"
}

error：稳定的 snake_case 错误码——请在您的业务逻辑中使用它。
message：面向人类的说明——可能变化，不要解析它。

已脱敏的错误信息。 错误的 message 绝不会暴露供应商名称、基础设施细节、URL、上游原始响应体（JSON/HTML）或内部配置——无论是 API 响应、webhook 还是持久化的状态字段都不会。来自支付处理方的业务性拒绝会保留可操作的失败原因（例如某份文件或账户为何被拒绝）；基础设施故障会被替换为固定的通用信息 "the payment provider could not process the request"——请使用相同的 idempotency_key 重试这些操作。

按类别划分的错误码

身份认证与权限

HTTP	`error`	含义
401	`unauthorized`	凭证缺失或无效
401	`invalid_credentials`	邮箱或密码错误（登录）
401	`invalid_refresh_token`	刷新令牌无效、已过期、已被使用或已被吊销 —— 请引导用户重新登录
403	`account_required`	该端点需要账户级凭证
403	`org_admin_required`	该端点需要管理员凭证
403	`forbidden`	凭证级别不允许
403	`account_blocked`	账户不是 active；这也会阻止 `POST /v1/me/verification/link` —— 请联系管理员恢复账户
403	`verification_rejected_requires_admin`	合规团队已拒绝该账户的 KYC/KYB；已禁用自助入驻 —— 请联系管理员重新开放验证
403	`member_disabled`	该用户已被禁止登录；请联系您组织的管理员
403	`passkey_rejected`	通行密钥（passkey）验证失败；请重试或使用密码登录
403	`owner_required`	只有账户的 owner 成员才能执行该操作
403	`service_disabled`	该服务未对您的账户启用（查看 `GET /v1/services`）
403	`org_suspended`	服务已暂停；请联系 CBPay 团队
403	`company_only`	仅企业账户可用的功能
403	`company_required`	仅企业账户可用的功能（例如第三方银行服务）
403	`human_session_required`	该操作涉及私钥（独立钱包导入/导出），需要带 2FA 的已登录用户会话——不允许使用 API 密钥

OTP / 双因素认证

完整流程和详情见安全与双因素认证。

HTTP	`error`	含义
403	`otp_required`	该操作需要 OTP：验证一个质询后携带 `X-OTP-Token` 重试
403	`otp_invalid`	OTP 令牌无效、已过期或已被使用
403	`session_required`	OTP 质询需要用户会话，不能使用 API 密钥
403	`phone_binding_cooldown`	手机号绑定未满 24 小时且未经验证，且没有替代因素（身份验证器应用或已验证邮箱）
409	`phone_verification_required`	通过 SMS/WhatsApp 启用登录 2FA 前需先验证手机号（OTP 挑战）
401	`invalid_code`	验证码不匹配
401	`invalid_pending_token`	登录中间令牌已过期；请重新登录
400	`invalid_action` / `invalid_channel`	操作或渠道不在目录中（质询 `channel` 须为 `sms`、`whatsapp`、`email` 或 `totp` 之一）
409	`phone_required`	账户未绑定手机号（`PATCH /v1/me`）
409	`otp_phone_missing`	登录需要 OTP 但账户没有手机号；请联系您的运营方
409	`challenge_not_pending`	质询已过期或已被使用；请创建一个新的
429	`too_many_attempts`	达到发送/验证次数限制；请等待几分钟
503	`otp_unavailable`	验证服务不可用（操作保持锁定；OTP 绝不会被跳过）
409	`otp_disabled_for_org`	您的组织未启用按操作的双因素认证；请联系您的运营方
409	`totp_not_started`	尚未开始 TOTP 注册；请先调用 `POST /v1/me/totp/enroll`

社交登录（OAuth）

完整流程和详情见社交登录。

HTTP	`error`	含义
400	`invalid_provider`	提供方不在 `google/apple/microsoft/facebook` 范围内
400	`provider_not_configured`	您的组织尚未启用该提供方
401	`invalid_credential`	提供方凭证无效、已过期或来自其他应用
409	`email_conflict`	已存在使用该邮箱的账户；请先登录再绑定该提供方
409	`identity_taken`	该提供方身份已绑定到其他账户
409	`last_login_method`	无法解绑您唯一的登录方式

组织管理面板

以下错误码来自组织管理界面（CBPay Admin 面板），并非上文所述的账户级 API —— 它们不会出现在账户级 /v1/* 端点中。

HTTP	`error`	含义
403	`global_treasury_access_disabled`	该组织尚未在其管理面板启用全局资金总览；请联系平台管理员在组织设置中启用 `global_treasury_read`
503	`core_admin_credential_missing`	平台管理员目录需要配置核心凭证；请联系平台管理员
400	`invalid_value`	组织设置的值类型有误（例如 `global_treasury_read` 必须是布尔值，而不是字符串）
409	`approval_in_progress`	另一位管理员正在处理此 adjustment；请等待当前操作完成后再重试

校验（400）

`error`	含义
`invalid_json`	请求体不是有效的 JSON 或包含未知字段
`invalid_lang`	`lang` 必须为 `es`、`en` 或 `zh`
`invalid_settings`	组织设置不是有效的 JSON 对象或无法规范化；请修正设置请求体后重试
`invalid_type`	`type` 必须为 `person` 或 `company`
`invalid_email` / `invalid_display_name`	必填字段无效
`weak_password`	密码少于 8 个字符
`invalid_role`	成员角色无效
`unknown_org`	组织 slug 错误（应使用 `cbpay`）
`invalid_request`	缺少 `country`/`currency`
`invalid_purpose`	`purpose` 必须是 `fondeo` 或 `banking`；请选择受支持的 Banking 走廊
`idempotency_key_required`	缺少幂等键
`unsupported_document_type`	不支持的文档类型；请使用受支持的文档类型
`invalid_document_file`	文档文件无效；请上传有效的 PDF、JPEG 或 PNG 文件
`reserved_idempotency_key`	幂等键使用了系统保留前缀（`payin-convert:` 或 `checkout-swap:`，属于自动转换）——请改用其他键
`beneficiary_required`	缺少付款收款人信息
`invalid_cuit`	阿根廷（`AR`）payout 要求 `beneficiary.tax_id` 为 11 位 CUIT 或 CUIL — 请发送收款人的 11 位标识；参见payout 指南
`invalid_cbu`	阿根廷（`AR`）payout 要求 `beneficiary.account_number` 为 22 位 CBU 或 CVU；USD payout 仅接受 CBU — 请发送有效的 22 位 CBU/CVU（USD 使用 CBU）；参见payout 指南
`invalid_amount`	金额不是有效的正十进制数
`recipient_required` / `self_transfer`	转账目标无效
`invalid_chain` / `invalid_asset`	不支持的网络或资产
`to_address_required`	缺少提现目标地址
`invalid_payload`	缺少必填字段（例如 AML 监控的 `enabled`、身份验证的 `external_customer_id`）
`invalid_iban`	SEPA payout 的 IBAN 无效、不支持 `EU` 路由，或在 SEPA Instant V1 中属于 GB；请修正后使用新的幂等键重试
`invalid_qr_payload`	出金二维码不可读或不受支持（BR Code 损坏、校验和无效或动态 PIX 二维码）；`message` 说明具体原因
`liveness_already_completed`	该验证的活体检测已经通过
`invalid_event_type` / `weak_secret` / `invalid_callback_url`	Webhook 订阅无效
`invalid_phone`	手机号无法规范化为 E.164 格式（联系人和 `to_phone`）
`invalid_language`	PDF 报告的 `lang` 不是 `en`、`es` 或 `zh`（AML 报告与验证报告）
`invalid_locale`	`PATCH /v1/me`（或注册）发送了非空且不属于 `en` / `es` / `zh` 的 locale。空字符串会存为英语。不同于 `invalid_language`（PDF 报告的 `lang`），也不同于组织管理员在 `default_locale` 上的 `invalid_value`
`invalid_format`	验证报告的 `format` 不是 `pdf` 或 `json`
`batch_too_large`	联系人导入超过 1,000 条（请分批上传）
`invalid_body`	无法读取请求体（二进制上传、webhook）
`invalid_image`	头像请求体为空或不是支持的图片格式（PNG/JPEG/WebP，最大 512 KB）
`invalid_interval`	订阅的 `interval` 必须是 `daily`、`weekly`、`monthly` 或 `yearly`
`query_required`	`GET /v1/resolve` 需要 `alias=` 或 `qr=` 参数
`same_email`	新登录邮箱与当前邮箱相同；请改用 `POST /v1/me/email/verify` 进行验证
`invalid_status` / `invalid_kyc_status` / `invalid_direction` / `reason_required` / `account_id_required` / `invalid_service` / `invalid_fee`	管理端校验
`invalid_settlement_hours`	`settlement_hours` 仅支持 `payin_card` 费用服务，且必须是非负整数（`0` = 立即入账）— 参见费用
`invalid_country`	国家/地区代码格式错误或缺失——ISO 3166-1 alpha-2（例如 `GET /v1/aml/catalogs/cities?country=`）；也用于有效但不支持的国家/地区过滤条件（例如在银行目录查询中传入非 `US` 的 `country`）

QR payin 幂等性

对于 method: "qr" 的 POST /v1/payins，idempotency_key 是可选的。可以在 JSON body 或 Idempotency-Key 请求头中发送；两者同时存在时以 body 中的值为准。key 最多 256 个字符，且不能包含 CR/LF。平台会在服务端按账户对 key 做命名空间隔离；集成方发送的 key 不会被改写。

400 invalid_idempotency_key：key 超过 256 个字符或包含 CR/LF。修正 key 后，用修正后的请求重试。
409 idempotency_conflict：相同 key 被用于不同国家、币种、方式或数值金额。要 replay，请保留原始 payload；要创建新收款，请使用新的 key。

相同 key 与相同 payload 会返回原始收款，并带有 idempotency_hit: true，不会创建第二笔收款。金额按数值比较（100 与 100.00 相同）；glosa 只是展示文本，不参与 replay 身份。使用 GET /v1/payins/{payinID} 查询实时状态。

资金与状态（402 / 404 / 409 / 422 / 429）

HTTP	`error`	含义
402	`insufficient_funds`	可用余额不足——对于银行转出，校验包含通道费用（`余额 ≥ 金额 + 费用`）；不满足时不会创建该操作
404	`not_found`	资源不存在（或属于其他账户）
404	`not_available`	所请求语言下不存在该文档
404	`country_not_found`	未知的 ISO 3166-1 alpha-2 国家/地区代码（城市目录）
404	`bank_not_found`	该 routing number 或 SWIFT/BIC 不在嵌入式银行目录中——payout/交易对手表单保持手动填写
404	`postal_code_not_found`	未知邮政编码，或该国家/地区没有数据集（邮政编码查询）——地址字段保持手动填写
404	`recipient_not_found`	转账目标不存在
404	`verification_not_found`	账户尚未提交任何验证（在完成入驻前调用 `GET /v1/me/verification/report`）
409	`duplicate`	资源已存在
409	`receipt_not_available`	技术筛查等待期间或扣款前筛查失败后，payout 暂无回执；请等待最终财务状态
403	`verification_requires_2fa`	新的自助 KYC/KYB 链接申请需要已确认的 TOTP 或已注册的通行密钥；已有开放链接会在此 gate 之前重新返回。解决方法：注册一个因子后重试 `POST /v1/me/verification/link`
403	`verification_required`	您的账户尚未通过身份验证（个人=KYC，企业=KYB）；获批前不能创建认证 payin、collect、专属入金账户、已保存卡扣款或订阅——请通过 `POST /v1/me/verification/link` 申请审核链接；被动入账和读取仍可用
422	`verification_required`	该操作需要一项已通过的第三方验证的 `verification_id`（第三方银行账户登记、指定持卡人卡片）
422	`verification_not_approved`	所引用的验证尚未通过
422	`verification_kind_mismatch`	验证类型与产品不匹配（KYC ⇒ person/INDIVIDUAL，KYB ⇒ company/COMPANY）
422	`verification_invalid`	在需要第三方验证的场景引用了自身入驻的验证
403	`company_account_required`	第三方验证（KYC/KYB 链接/提交）仅限企业账户
409	`already_verified`	使用已通过验证的账户请求了入驻链接
409	`identity_locked`	验证获批后，`display_name`、`tax_id` 和 `country` 来自已验证的身份，无法通过 `PATCH /v1/me` 修改；请联系支持
409	`no_screening`	在没有先行筛查的情况下发起 AML 重新筛查/监控
409	`no_banking_customer`	传统 Banking 操作没有通用 banking profile（先调用 `POST /v1/banking/customer`）；EUR Banking 走直接虚拟 IBAN 流程
400	`banking_eur_requires_viban`	EUR Banking 账户通过虚拟 IBAN 开立。请在 Operar EUR 中请求 `purpose: "banking_eur"`，不要创建通用 banking customer
409	`banking_customer_exists`	该账户已有银行账户资料（每个账户仅限一个）
409	`idempotency_conflict`	同一 banking profile claim 仍为 pending 或 payload 已变化——保持相同请求并等待核对
503	`banking_recovery_pending`	customer 创建结果不明确——运营人员必须先核对持久 claim，再使用新密钥重试
409	`bank_ref_conflict`	该银行参考号已被另一笔操作认领（属于你租户时，响应会用 `claimed_by`/`claimed_kind` 指明）——请修正证据，不要换参考号重试
503	`bank_ref_recovery_pending`	上一次确认使该银行参考号处于不明确状态，平台正在核对持久 claim——请用相同的确认（相同的参考号和 idempotency key）重试；重试会恢复而不会重复
422	`currency_not_supported`	该货币没有汇率
422	`core_rejected`	处理方拒绝了该操作 —— 当消息报告账单地址不完整（或缺少州/省）时，已保存的卡没有可用的账单地址：请让付款人通过 `save_card: true` 重新保存；处理方也可能在扣款前拒绝阿根廷 alias payout：alias 无法解析，或 USD alias 解析为 CVU；修正受益人后使用新的幂等键重试。
400	`invalid_payload`	对于 `method: "card"`，`expires_at` 必须是 RFC3339，至少提前 5 分钟且不超过 48 小时
422	`checkout_expiring_soon`	checkout 链接将在不到 5 分钟后过期。使用银行卡付款前，请向商户索取新的链接
429	`too_many_open_card_sessions`	账户已有 50 个开放银行卡会话，且没有可驱逐的零尝试 `pending` 会话 —— 请完成或等待现有会话过期后再创建
503	`card_recovery_pending`	平台正在核对一笔结果不明确的银行卡收款。请使用相同幂等键重试；不要生成新键或第二笔收款
409	`core_charge_terminal`	底层银行卡扣款已经处于最终状态，因此平台不会再次入账 —— 读取当前 payin/扣款状态，切勿创建第二笔扣款
503	`card_reuse_unavailable`	平台无法核对现有的开放银行卡收款。请使用相同幂等键重试原始请求；不要创建第二笔收款
503	`core_reuse_unavailable`	core 未返回完整且可恢复的银行卡会话。请使用相同幂等键重试原始请求
422	`recipient_unavailable`	目标账户无法接收
422	`recipient_ambiguous`	多个账户共用该 `to_phone` 号码（请使用 `to_account_id` 或 `to_email`）
422	`contact_not_linked`	该联系人没有可转账的已关联 CBPay 账户
422	`no_saved_destination`	该联系人在该通道/链上没有已保存的目标
422	`wallet_limit_reached`	该账户在此网络+资产组合下已持有对应钱包（充值钱包：所有账户；隔离钱包：个人账户）
422	`insufficient_gas`	独立钱包没有支付网络费所需的原生 gas（TRX/ETH）；请为该地址充值后重试
409	`idempotency_conflict`	使用相同幂等键的另一次钱包创建/转出仍在进行中；请使用同一个键重试
400	`physical_temporarily_unavailable`	新实体卡发行暂时暂停；请申请虚拟卡。已经发行的实体卡继续正常使用。
409	`card_limit_reached`	个人账户已有一张有效卡或一条开放申请；请先处理现有申请再申请新卡
409	`card_cancelled`	卡片已注销，无法更新
409	`card_not_pending`	只有处于 `pending_activation` 状态的卡片才能激活
409	`cardholder_kyc_pending`	指定持卡人需要提交身份证明文件
400	`invalid_occupation`	`occupation` 不是目录中的代码（`GET /v1/cards/catalog/occupations`）
400	`invalid_kind_of_business`	`kind_of_business` 不是目录中的代码（`GET /v1/cards/catalog/business-activities`）
422	`issuer_data_incomplete`	request、验证自动填充和 KYB 派生数据组装后仍缺少或存在无效的发卡方字段；请根据 `message` 中列出的键修正并重试
422	`screening_required`	账户没有可用于派生持卡人 PEP 的 AML 身份验证 screening；请完成 screening 后使用同一个卡片 request 重试
422	`cardholder_name_too_long`	个人的 `first_name` 与 `last_name` 合计超过发卡方 22 个字符的卡面打印限制；请缩短姓名后重试
400	`invalid_settlement_asset`	`settlement_asset` 不是 USDT、USDC、BTC 或 GOLD
400	`settlement_asset_disabled`	您的组织已禁用该资产作为结算来源
422	`settlement_limit_exceeded`	该操作超出波动性资产（BTC/GOLD/SILVER/PLATINUM）的单笔操作限额；请使用 USDT/USDC 或拆分操作
422	`settlement_daily_limit_exceeded`	该账户已超出波动性资产（BTC/GOLD/SILVER/PLATINUM）的 24 小时交易量限额；请使用 USDT/USDC 或稍后重试
422	`guard_diverged`	BTC 价格参考值超出交易前价格保护的偏差上限；等待价格收敛或拆分操作，并使用相同幂等键重试
400	`invalid_pair`	兑换（swap）的源货币与目标货币相同
400	`amount_too_small`	兑换金额不足目标货币的最小单位
400	`swap_asset_disabled`	兑换涉及的某一货币已被您的组织禁用
409	`already_paid`	通用收款链接已通过其他方式支付
410	`checkout_expired`	通用收款链接到期未支付
422	`method_unavailable`	收款链接上所选方式对该链接或国家不可用
400	`country_required`	收款链接的法币物化缺少 `?country=XX`
400	`currency_required`	该国家以多种币种提供收款链接的方式；缺少 `?currency=YYY`
422	`country_unavailable`	该国家在收款链接上没有可用的支付方式
422	`collect_otp_failed`	通道拒绝发送链接拉取式收款的 OTP
422	`collect_rejected`	通道拒绝了链接的拉取式扣款（OTP 无效或数据错误）；链接保持待支付
422	`provider_rejected`	对于 `VE/VES/c2p`，不要调用 `/collect/otp`；付款人会把银行生成的 `claveDinamica` 放在 collect 请求的 `otp` 字段中。Adapter 内部信号为 `collect_otp_unsupported`。
422	`settlement_asset_disabled`	收款链接的 `settlement_asset` 已被您的组织禁用
422	`checkout_amount_mismatch`	CBPay 转账不足以覆盖收款链接的当前应付额；错误消息附带最新金额
503	`checkout_recovery_pending`	所选 checkout 支付选项正在核对。请重试相同的物化请求；不要创建第二个支付选项
422	`stored_card_revoked`	已保存的卡片已被撤销；不再接受扣款
422	`verification_required`	QR Crypto POS：用商户已批准的第三方 KYC/KYB 的 `verification_id` 注册商户
422	`merchant_disabled`	QR Crypto POS 商户已停用；先重新启用再生成收款
422	`nothing_received`	QR Crypto POS 收款未收到任何链上支付：无可退款
422	`refund_exceeds_received`	退款超过 QR Crypto POS 收款已收金额减去已退金额
503	`refund_recovery_pending`	退款关联暂时不可用；请使用相同的幂等键重试，不要发起第二笔提现
400	`to_address_required`	QR Crypto POS 退款（及加密货币提现）必须显式提供目标地址
422	`deposit_account_limit_reached`	个人账户和未支持或既有通道每个通道只有一个账户；企业 banking 每个启用通道最多 50 个账户
400	`invalid_label`	本地充值账户昵称超过 60 个字符；缩短后重试
409	`alias_pending`	AR/ARS 企业 banking CVU 尚未设置银行 alias；先调用 bank-alias PUT，再读取余额或流水
422	`purpose_not_supported`	余额和流水仅适用于 `purpose: "banking"` 工具
422	`ambiguous_source_instrument`	存在多个活跃 BO/BOB banking 来源；在 `source_instrument_id` 中发送所选 UUID
422	`invalid_source_instrument`	所选来源不是活跃的 BO/BOB banking 工具；请选择有效目的地
409	`intent_abandoned`	第三方验证被拒绝；请求 banking 前先创建新的验证链接
409	`deposit_account_conflict`	core 返回的充值目的地已分配给其他组织——先完成对账再重试

合规（403 / 503）

HTTP	`error`	含义
403	`compliance_hold`	该操作已被平台的合规控制拦截。这不是请求错误：请携带时间戳联系支持团队 — 根据政策，不会披露具体原因
403	`geo_restricted`	该服务或操作不适用于发起方或交易对手所在的司法辖区
503	`compliance_check_unavailable`	合规校验无法完成，且 payout 无法写入技术筛查队列；请使用相同幂等键重试。队列可用时，`POST /v1/payouts` 会返回 `202` 且资源为 `status: pending`。其他校验和安全错误仍使用各自代码
422	`travel_rule_required`	超过 Travel Rule 阈值的链上提现缺少受益人数据 — 补充 `travel_address` 或 `wallet_type: "self_hosted"` + `beneficiary_name`（加密货币指南）
422	`travel_rule_beneficiary_required`	适用 Travel Rule 的提现缺少 `beneficiary_name`
422	`travel_rule_address_mismatch`	您的 `to_address` 与收款机构批准的付款地址不一致 — 省略它或使用交换返回的地址
422	`travel_rule_rejected`	收款机构拒绝了该转账；请核对受益人数据
422	`travel_rule_pending`	收款机构尚未处理该交换；请使用相同的幂等键重试
422	`travel_rule_incomplete_approval`	收款机构批准时未提供付款地址；请联系支持团队
503	`travel_rule_unavailable`	Travel Rule 数据交换暂时不可用；请使用相同的幂等键重试

Qscore

信用局端点的错误(指南)。

HTTP	`error`	含义
400	`purpose_required`	创建报告时缺少 `purpose` — 数据保护法要求声明用途(`credit_evaluation`、`tenant_screening`、`hiring`、`supplier_onboarding` 或 `other`)
400	`invalid_purpose`	`purpose` 不是允许的值之一(`credit_evaluation`、`tenant_screening`、`hiring`、`supplier_onboarding`、`other`)— 请修正该值。`self_access` 在此被拒绝:您自己的报告只能通过 `POST /v1/qscore/my-report` 获取
400	`invalid_doc_id`	`doc_id` 在给定的 `country` 无效(例如智利 RUT 校验位错误)— 修正证件格式
400	`invalid_subject_type`	`subject_type` 不是 `person`/`company` 且无法从证件推断 — 请显式发送
400	`invalid_tax_id`	账户已验证的 `tax_id` 在其国家/地区无效(自助报告)— 请联系客服修正您的已验证信息
403	`kyc_required`	生成您自己的报告需要已批准的 KYC/KYB — 请先完成身份验证
403	`report_required`	启用监控需要先购买该主体的报告 — 请先购买(指南);出于隐私保护,主体不存在时也会返回相同的响应
404	`no_score`	该主体尚无已计算的评分 — 请先购买报告
404	`pdf_not_ready`	报告 PDF 尚不可用 — 轮询详情直到 `status=ready`(`risk_report_ready` webhook 会通知你)
409	`no_tax_id`	已验证账户没有 `tax_id` 记录,自助报告无法解析其主体 — 请先完善您的已验证信息
409	`identity_mismatch`	账户的 `tax_id` 与已验证的身份文件不符(自助报告)— 请联系支持;您的已验证数据必须一致
400	`no_valid_items`	批次中的所有行均被拒绝(`invalid_doc_id` / `duplicate_in_batch`),且未创建任何批次 — 请在本地校验文件(每个 `doc_id` 必须通过该国校验位且保持唯一),然后使用新的幂等键重新提交
400	`too_many_items`	单个批次最多接受 5,000 个主体 — 请将投资组合拆分为多个批次,每个批次使用各自的幂等键
409	`already_decided`	授权链接已被处理(`granted`、`revoked` 或 `expired`),无法再次变更状态 — 如需重新授权,请创建新的链接
409	`link_inactive`	授权背后的银行连接未处于 `active` 状态(widget 会话已过期或链接已被撤销)— 持有人需通过同一授权链接重新连接
409	`holder_mismatch`	银行验证的证件与主体的 `doc_id` 不一致 — 属于其他证件的账户永远无法授予授权;请确认为正确的证件创建了链接
409	`seal_companies_only`	Qscore 公开印章仅适用于企业账户 — 个人账户没有印章(指南)
409	`seal_not_eligible`	该账户的 Qscore 当前不符合公开印章资格(等级 A 或 B,且评估不超过 90 天)— 请先购买最新报告(指南);若等级仍低于 B,印章在分数提升前不可用
404	`no_active_seal`	该账户没有可撤销的有效印章 — 请先通过 `POST /v1/qscore/my-seal` 激活;已撤销的印章将永久失效(可创建新印章)

交易防火墙

被交易防火墙挂起的操作在审核时返回的错误（见指南）。挂起本身不是错误：创建请求返回 202 Accepted 并携带 status: in_review 和 review_id。

HTTP	`error`	含义
400	`invalid_status`	`status` 过滤条件无效——请使用 `in_review`、`info_requested`、`released`、`rejected` 或 `all`
400	`invalid_range`	`from`/`to` 日期无效——格式为 `YYYY-MM-DD`（组织时区）
400	`invalid_name`	缺少查询参数 `name` 中的文件名（最多 200 个字符，不含路径分隔符）
400	`empty_file`	文件请求体为空
404	`not_found`	该审核或文件不属于您的账户——设计上绝不返回 403
409	`not_awaiting_info`	该审核不在等待信息（已回到 `in_review` 或已有最终决定）——请查询其当前状态
413	`file_too_large`	文件超过 50 MB 上限——请压缩或拆分
415	`unsupported_file_type`	不支持的类型——请使用 PDF、PNG、JPEG、WEBP、TXT、CSV、DOC(X) 或 XLS(X)，并携带正确的 `Content-Type` 请求头
422	`file_limit_reached`	该审核已有 20 个文件
503	`firewall_unavailable`	无法评估策略或无法保存审核——请使用相同的幂等键重试
503	`storage_unavailable`	文件存储暂不可用——请稍后重试

实时事件（SSE）

来自 GET /v1/events 及其历史查询的错误码。

HTTP	`error`	含义
400	`invalid_event_type`	`?types=` 中的某个值不在目录内 — `message` 会列出有效值
429	`too_many_streams`	已达到并发流上限（按账户或按组织）— 请先关闭一个再打开新的
429	`rate_limited`	该 IP 打开事件流过于频繁（每小时 600 次）— 该配额统计尝试次数而非活动连接：请停止重连循环并采用退避策略
500	`streaming_unsupported`	该连接不支持流式传输（中间代理在缓冲）— 关闭缓冲或改用 Webhook
503	`stream_unavailable`	无法打开事件流；请携带 `Last-Event-ID` 退避重试

消息签名与钱包绑定

来自钱包消息签名的错误码（EVM 上的 EIP-191、TRON 上的 TIP-191）：使用隔离钱包的服务端签名（POST /v1/segregated-wallets/{id}/signatures，会生成可公开验证的签名证明），以及通过挑战绑定外部钱包（POST /v1/wallet-links/challenges → 用你的钱包签名挑战 → POST /v1/wallet-links/verify）。

HTTP	`error`	含义
400	`unsupported_chain`	`chain` 必须是 `tron` 或 `eth`
400	`invalid_statement`	`statement` 超过 280 个字符 — 请缩短（注意：签名信封本身最多接受 140 个字符）
409	`proof_not_signable`	该证明已不再处于可签名状态（已签名、已过期或已取消）— 请重新申请
409	`custody_transferred`	钱包托管权已转移给客户，无法再使用服务端签名 — 请用您自己的私钥签名
409	`challenge_consumed`	该挑战已被使用或已失效 — 请重新申请
410	`challenge_expired`	该挑战已过期 — 请重新申请并在有效期内完成签名
422	`signature_mismatch`	签名与挑战地址不匹配 — 请用要绑定的钱包对挑战原文进行签名
422	`sign_rejected`	签名方拒绝了该请求 — `message` 中包含已脱敏的原因。141–280 个字符的 `statement` 也会在此处被拒绝（信封最多接受 140 个字符）

服务端（5xx）

HTTP	`error`	含义
500	`internal_error`	意外错误；请使用相同的幂等键重试
500	`fee_config_invalid`	账户的费用配置无效；请联系支持（该操作未执行）
502	`rates_unavailable`	汇率暂时不可用
502	`core_unavailable`	处理方暂时不可用
502	`core_invalid_response`	处理方返回了意外响应；请使用相同的幂等键重试
502	`compliance_unavailable`	AML 筛查暂时不可用
503	`verifications_unavailable`	身份验证暂时不可用
503	`org_credential_missing`	服务正在配置中；请联系 CBPay 支持
503	`withdrawals_unavailable`	该通道未启用链上提现
503	`pricing_unavailable`	BTC/GOLD/SILVER/PLATINUM 执行价格不可用或已过时；请稍后重试或以 USDT/USDC 结算
503	`channel_unavailable`	出金通道暂时不可用；请稍后使用相同的幂等键重试
503	`webhook_processing_pending`	入站 webhook 事件正在处理中；短暂退避后重试同一条投递，不要创建新的操作
503	`export_unavailable`	当前环境未启用独立钱包私钥导出

如何处理

校验类 4xx：修正请求。不要原样重试。
402：为账户充值后重试（仅当操作从未被创建时才使用新的幂等键）。
5xx / 超时：使用相同的幂等键重试；操作绝不会重复。

Qscore 欺诈与 Index

HTTP	`code`	含义与处理
400	`invalid_period`	Index 时期不是 `YYYY-Q1` 到 `YYYY-Q4`；请使用已关闭季度
422	`unsupported_country`	所选国家暂不支持 Qscore 欺诈/身份流程；请选择支持的国家或联系支持
503	`recovery_pending`	欺诈报告仍在完成中；使用相同凭证轮询报告，状态变为 `ready` 后再重试 PDF
429	`too_many_attempts`	公开欺诈验证被限流；稍后重试
502	`generation_failed`	费用路径之后生成失败；费用已退回，使用新的幂等键重试

走廊生命周期

HTTP	代码	含义与处理
409	`corridor_disabled`	所选走廊被管理员禁用。请选择其他启用的 method 或联系组织运营人员。

Banking 创建恢复错误

代码	HTTP	含义与处理
`claim_identity_mismatch`	422	提供商客户身份与原始 banking 请求不匹配。停止恢复并检查 claim。
`idempotency_failed`	409	claim 已彻底失败。检查失败原因后，使用新 key 发起新操作。
`claim_not_pending`	409	claim 已不再处于待处理状态。读取最终结果，不要重复恢复。
`claim_customer_owned_elsewhere`	409	提供商客户已归属于其他账户。停止并检查所有权。
`banking_recovery_pending`	503	提供商结果仍不明确。使用管理员恢复路由，不要再次发起创建请求。

EUR Banking 与虚拟 IBAN 错误

Code	Meaning and action
`banking_customer_incomplete`	The banking customer lacks the provider identity required for the operation. Complete the customer/KYC/KYB data, then retry with the same idempotency key.
`registrant_incomplete`	422	虚拟 IBAN 申请	已验证的 KYC/KYB profile 缺少 registrant 必填字段；按消息补充证件或公司注册数据，并重试相同申请。
`provider_rejected`	The upstream banking operation was rejected. Do not create a new money operation automatically; inspect the resource and follow its retry/reconciliation state.
`customer_id_required`	A banking operation requires an explicit customer identifier. Provide the customer ID from the account-owned resource.
`iban_required`	The operation requires the IBAN associated with the owned virtual account.
`operation_in_progress`	The same banking operation is still being reconciled. Poll the resource and retry with the original idempotency key.
`ownership_required`	The resource belongs to another organization or account. Use only an owned resource; never guess or substitute an ID.

账户批量消息错误代码

以下代码来自组织管理 broadcast 端点，便于共享 SDK 使用统一的错误目录。

HTTP	`error`	原因	解决方法
400	`invalid_channels`	未选择有效的发送渠道	发送 `email`、`notification` 或二者
400	`invalid_content`	subject/body 为空或过长	subject 使用 1–160 个 rune，body 使用 1–4000 个 rune
400	`invalid_audience`	受众模式、筛选器或 ID 无效	使用 `filters` 或 1–5000 个组织内账户 ID
400	`invalid_reason`	缺少拒绝原因或原因过长	发送 1–500 个 rune 的审计原因
403	`named_admin_required`	actor 不是命名管理员	使用命名的 `god` 或 `super_admin` 管理员
403	`partner_forbidden`	bank partner 尝试使用组织 broadcast	使用允许的组织管理员
409	`empty_audience`	提交/审批时没有账户匹配	修正受众后重新提交
409	`audience_too_large`	筛选器匹配超过 20000 个账户	缩小筛选范围后重新提交
409	`second_approver_required`	创建者尝试审批自己的 campaign	让另一名命名 God 审批

Banking EUR 与企业钱包错误

HTTP	代码	处理
409	`virtual_iban_limit_reached`	个人账户该 purpose 已有虚拟 IBAN；请复用它，企业不受同样的 purpose 上限。
409	`no_fee_charged`	该虚拟 IBAN 未收费（首个注资免费），无需退款。
409	`wallet_not_ready`	钱包仍为 `pending`/`provisioning`；读取详情直到变为 `active`。
422	`virtual_iban_limit_reached`	预留时达到个人账户的 purpose 上限；不要创建第二个 key。
422	`registrant_incomplete`	按 `message` 补充 KYC/KYB 或公司注册字段，并重试同一持久化请求。
502	`wallet_reservation_failed`	预留没有返回可用 reference；先协调再重试。
502	`wallet_reservation_status_failed`	状态读取失败；保留 `order_reference` 或 `client_order`。
502	`wallet_read_failed`	live wallet 响应或 EUR 金额不可读；检查状态后重试读取。
502	`wallet_statement_failed`	statement 不可读；使用完整日期窗口后重试读取。

账户集成策略

HTTP	`error`	含义与处理
400	`email_domain_blocked`	邮箱域名被阻止；使用允许的域名。
400	`invalid_secret`	Webhook secret 必须为 16 到 256 个字符。
403	`session_required`	创建账户 API key/Webhook 需要人工 JWT，而不是 API key。
403	`integration_company_only`	个人账户需要有效管理员授权；企业账户需要 KYB 批准。
403	`integration_kyb_required`	先批准 KYC/KYB，再创建或重新启用集成。
403	`account_blocked`	账户不是 active；请让管理员恢复账户。
403	`otp_required`	完成 `api_key_create` 或 `webhook_manage` OTP 后重试。
403	`integration_forbidden`	账户不能使用集成；查询 `GET /v1/integration-status` 并处理返回的资格原因。

争议与欺诈

HTTP	代码	处理
400	`idempotency_key_required`	金融操作在 body 或 header 中发送幂等键。
400	`invalid_payload`	修正金额、日期、UUID、multipart 文件或必填字段。
404	`not_found`	案件、导入、行、证据或账户超出调用者 scope。
409	`case_already_open`	查看 payin 的开放案件，不要创建新键。
409	`payin_not_credited`	payin 尚未处于 `credited` 状态，因此没有可冻结的余额；等待入账后再打开案件或绑定导入行。
409	`second_approver_required`	必须由另一名具名管理员关闭。
409	`invalid_state`	当前状态不允许该转换。
409	`bind_failed`	导入行不再是 unmatched 或 payin 无法关联。
409	`import_in_progress`	相同 key 的导入仍在处理中；等待后用相同 key 重试。
503	`pack_unavailable`	storage 或 PDF 渲染恢复后重试。
503	`storage_unavailable`	恢复私有 storage 后重试证据操作。

SEPA 资金来源错误

这些错误会在客户 payout 或 EUR Banking 操作扣款、dispatch 之前返回：

HTTP	`error`	含义与解决方法
400	`invalid_request`	`source_virtual_iban_id` 必须是有效 UUID。
404	`not_found`	明确指定的虚拟 IBAN 不属于该账户。
422	`funding_account_required`	该产品用途没有已分配且 active 的虚拟 IBAN。请先使用该用途的 active 来源。
422	`ambiguous_source_viban`	存在多个 active EUR 资金账户。请发送选定的 `source_virtual_iban_id`。
503	`funding_account_unavailable`	来源账户检查暂时不可用。请使用相同幂等键重试；不会发生扣款或 dispatch。

出金限额错误

HTTP	`error`	含义
422	`amount_below_minimum`	金额低于有效最小值；读取 `GET /v1/org/txn-firewall/limits/effective`。
422	`amount_above_maximum`	金额高于有效最大值；重试前先检查有效策略。
422	`velocity_limit_exceeded`	内部转账超过滚动金额或次数上限。Payout 和 crypto withdrawal 会以 `reason=velocity_limit` 进入 review。
503	`limits_unavailable`	扣款前无法评估限额；恢复后使用同一幂等键重试。

`dispute_fiat_unsupported`

本地保留 BOB、MXN 或 ARS 的 payin 暂不支持争议。请使用受支持的 USD 或 USDT 入账，或等待本地法币争议功能。

阿根廷银行别名与个人资料别名

HTTP	`error`	含义 / 处理方式
400	`missing_alias`	平台创建 AR/ARS 存款账户时必须提供调用方选择的 `bank_alias`
400	`invalid_alias`	`bank_alias` 必须为 6–20 个 `[A-Za-z0-9.-]` ASCII 字符，并至少包含一个字母
400	`invalid_account`	core 无法解析提供的存款账户号码
400	`invalid_request`	个人资料别名 body 不匹配已验证姓名派生的候选值，或在不支持的通道发送了 `bank_alias`
409	`alias_already_set`	个人资料别名永久有效，已经设置
409	`alias_taken`	个人资料别名：已验证姓名派生的所有候选值都被占用；请联系支持，不能自行编造值
422	`alias_taken`	银行别名：阿根廷银行系统已占用该值；请选择其他值
422	`alias_unsupported`	选择的存款账户通道不支持银行别名

Grupo CB 主协议签署仪式

以下错误适用于 POST /v1/me/contracts/envelopes/{envelopeID}/sign 和合同信封资源。为保护隐私，message 可能是固定的泛化文本；code 是稳定的集成契约。

HTTP	Code	原因与解决方法
400	`idempotency_key_required`	组织管理员签发缺少 body key 或 `Idempotency-Key`；使用稳定 key 重试。
400	`invalid_idempotency_key`	key 无效或过长；缩短后重试。
400	`invalid_reason`	void 必须提供非空原因；把原因放入 body。
400	`invalid_content_type`	签名图库只接受 `image/png`、`image/jpeg` 或 `image/jpg`。
400	`empty_file`	上传没有字节；发送原始图片文件。
400	`invalid_image`	文件不是有效 PNG/JPG；重新导出支持的格式。
403	`contract_counsel_required`	英文签发需要 counsel 批准；批准或使用西班牙语。
403	`human_session_required`	签署需要人工 session；API key 不能签署。
403	`account_blocked`	账户不是 active；请管理员恢复。
401	`invalid_otp`	OTP 无效、过期或已使用；在 `X-OTP-Token` 中发送新的 token。
409	`contract_invalid_state`	信封已经 completed 或 voided；不要重复操作。
422	`contract_template_superseded`	信封使用旧版模板签发；签署前请先重新签发。
413	`file_too_large`	raw 上传超过 5 MiB，或规范化图片超过 8 MiB。
422	`invalid_lang`	只能使用 `es` 或 `en`。
422	`contract_account_ineligible`	目标必须是 KYB 已批准的 active 企业账户。
422	`contract_unfillable`	请检查响应中的 `missing` 数组：其中可能列出身份资料、法律顾问批准，或表示已启用服务缺少有效价格行的 `pricing:<flag>`。
422	`invalid_consent`	body 必须包含 JSON 布尔值 `"consent": true`。
422	`invalid_signer`	姓名/职务为空或过长；使用 owner/operator 人工签署人。
422	`invalid_signature_image`	`signature_png` 不是有效或有墨迹的 PNG，超过编码/解码大小限制，或未达到最小尺寸；发送有效签名图片并使用新 OTP 重试。
502	`storage_failed`	私有 storage 失败；重试前先协调信封状态。
502	`email_failed`	签署后邮件失败；已完成信封仍然有效。
503	`storage_unavailable`	私有 storage 不可用；恢复后重试。

环境切换

HTTP	`error`	含义与处理
401	`invalid_handoff`	缺少 handoff token、已过期、已消费，或签发给另一个环境。请签发新的 handoff 并在同一环境兑换。
401	`handoff_replayed`	该 token 已被消费（一次性）。请签发新的 handoff。

双因素与 passkey

HTTP	`error`	含义与处理
403	`channel_locked_by_org`	组织策略仅允许 TOTP，禁止该账户注册 passkey；也会拒绝显式 `channel` 弱于组织底线的质询。请联系 org 管理员修改策略。
409	`passkey_exists`	该 credential ID 已注册在此账户。请用现有 passkey 登录。
409	`totp_already_enrolled`	该账户已激活 TOTP。请用现有 secret 认证。

Checkout 与 payout 文档

HTTP	`error`	含义与处理
409	`materializing`	该 checkout 链接的另一笔实例化正在进行中。请等待完成后重试。
400	`invalid_file_name`	文件名为空、过长，或含路径字符（`/`、`\`、`..`）。请发送纯文件名。
415	`unsupported_media_type`	Content-Type 不是可接受的文档类型。请发送 PDF、JPEG 或 PNG。

`destination_recently_rejected`

HTTP	代码	含义	处理方式
422	`destination_recently_rejected`	银行最近拒绝了此账户的同一规范化收款目的地。系统不会创建 payout、不会扣除余额，也不会消耗幂等键。	先使用相同的幂等键重放原始请求。如需明确重试，请使用新的幂等键，并将 `options.destination_retry_ack` 设置为最近一次被拒 payout 的 ID。

确认值只对该目的地最近一次拒绝有效。使用相同幂等键但修改 options 会返回 idempotency_conflict（409）。其他 payout 方式以及没有近期拒绝记录的目的地继续走正常的校验和发送流程。

身份验证抗攻击加固错误

HTTP	`error`	含义与处理
400	`invalid_code`	注册或重置验证码不是 4–10 位数字。请按预期格式发送验证码。
401	`invalid_code`	注册确认或密码重置的身份/验证码无效或已过期。请使用最新验证码；该响应为有意统一的。
401	`invalid_credentials`	登录失败、账户待验证，或账户在 15 分钟内失败 8 次后被暂时锁定。请等待窗口结束或完成注册确认。
502	`otp_check_failed`	无法查询验证服务。请保持同一流程稍后重试；不要创建第二个账户或重置请求。

POST /v1/auth/password/forgot 为防止枚举始终返回 200。每个账户每小时静默停止实际发送（上限 5 次）；POST /v1/auth/password/reset 允许每个账户每 15 分钟尝试 8 次验证码。

成员恢复链接

HTTP	`error`	原因与处理
400	`invalid_token`	`token` 不是恢复邮件中 43 个字符的 base64url 值。请原样复制 `?token=` 后的值。
400	`weak_password`	新密码不符合服务器策略。请选择更强的密码，并在链接仍有效时重新提交。
401	`invalid_token`	链接无效、已过期、已使用，或与组织/成员不匹配。请向组织管理员申请新链接；该响应有意保持统一。
502	`recovery_send_failed`	管理员发起的恢复邮件无法送达。请组织管理员检查邮件配置并重新触发链接。
429	`too_many_attempts`	来源 IP 超过验证 throttle。请稍等后重试，不要自动重复提交。

US/USD 出金校验

以下错误会在 ach、wire 和 swift 出金扣款前返回：

HTTP	`error`	含义与解决方案
400	`invalid_beneficiary`	收款人必填字段缺失或格式错误；按 `message` 修正，例如 `beneficiary.account_type`。
400	`invalid_amount`	金额不是有效的正小数；修正金额并创建新请求。
422	`amount_below_minimum`	`wire` 或 `swift` 低于 USD 25；使用至少 `25.00`。
422	`prohibited_country`	收款人或银行位于附录 B（`CU`、`IR`、`KP`、`SY`）；改用允许的目的地。
400	`purpose_required`	每笔 US/USD 银行通道出金都必须填写 `options.purpose`；请选择目录值。
400	`invalid_options`	选项未知，或非 `Other` 用途提供了 `purpose_detail`；修正 `options`。
400	`supporting_document_required`	创建 USD 银行通道出金前上传并传递发票或收据。

​按类别划分的错误码

​身份认证与权限

​OTP / 双因素认证

​社交登录（OAuth）

​组织管理面板

​校验（400）

​QR payin 幂等性

​资金与状态（402 / 404 / 409 / 422 / 429）

​合规（403 / 503）

​Qscore

​交易防火墙

​实时事件（SSE）

​消息签名与钱包绑定

​服务端（5xx）

​如何处理

​Qscore 欺诈与 Index

​走廊生命周期

​Banking 创建恢复错误

​EUR Banking 与虚拟 IBAN 错误

​账户批量消息错误代码

​Banking EUR 与企业钱包错误

​账户集成策略

​争议与欺诈

​SEPA 资金来源错误

​出金限额错误

​dispute_fiat_unsupported

​阿根廷银行别名与个人资料别名

​Grupo CB 主协议签署仪式

​环境切换

​双因素与 passkey

​Checkout 与 payout 文档

​destination_recently_rejected

​身份验证抗攻击加固错误

​成员恢复链接

​US/USD 出金校验