错误码与状态码

本文介绍了在使用 Cobo Payments API 时可能遇到的常见错误码和 HTTP 状态码，以及如何解决这些错误。当请求失败时，响应体中包含 error_code 字段（整数）、描述问题的 error_message 字段，以及可用于在 Cobo 日志中追踪请求的 error_id 字段。

错误码

通用 API 错误

错误码	HTTP 状态码	描述	解决方案
2006	400	一个或多个参数格式无效或包含不支持的值。	根据 API 参考验证请求体。检查参数类型、枚举值以及所有必填字段。`error_message` 字段通常会指明验证失败的具体参数。
2010	429	您已超出 API 访问频率限制。	降低请求频率。在重试前实施指数退避加抖动策略。
2024	401	API Key 认证失败。	请使用与当前环境对应的 API Key（例如开发环境使用开发 API Key，生产环境使用生产 API Key）。请确保您使用的 API Key 已在 Cobo Portal 上注册并处于活跃状态。如果您的 API Key 是永久的，请确保请求来自白名单 IP 地址。详情请参见发送首个请求。
2025	403	您的 API Key 没有执行此操作所需的权限。	在 Cobo Portal 中检查 API Key 的 OAuth scope 和角色分配。详情请参见角色与权限。
2026	429	请求过多。您的请求频率已超出服务器端阈值。	等待后重试。使用指数退避策略进行重试。
2027	400	您已超出此资源或操作的配额限制。	在 Cobo Portal 的设置 > 开发者下查看当前使用量和套餐限制。
2028	404	未找到请求的资源。	验证请求中的资源 ID（例如 `merchant_id`、`order_id`、`payer_id`）是否正确，且属于您的组织。
2029	400	资源的当前状态不支持所请求的操作。常见原因：(1) 在交易达到 `Completed`、`Rejected` 或 `Failed` 状态之前尝试更新交易描述；(2) 尝试取消一个不处于 `Generating` 状态的交易导出任务；(3) 您的支付开发者账户未处于活跃状态。	查看 `error_message` 字段了解具体原因。如需更新交易描述，请等待交易达到终态后再操作。如需取消导出任务，请确认该任务仍处于生成中状态。
2040	400	检测到重复键。具有此标识符的记录已存在。	为新记录使用不同的唯一标识符。

支付资源错误

支付相关的验证失败——例如资源未找到或字段值被拒绝——均返回 "error_code": 2006。使用响应中的 error_message 字段来识别具体原因。

场景	`error_message` 示例	解决方案
商户未找到	`Merchant {merchant_id} not found.`	验证 `merchant_id` 值是否正确，且属于您的组织。
订单未找到	`Order {order_id} not found.`	验证 `order_id` 值。订单限定在商户范围内——请确认该订单属于您指定的商户。
充值付款方未找到	`Topup payer {payer_id} not found.`	验证 `payer_id` 值。付款方是按商户创建的。
Token 不支持	`Unsupported token {token_id}`	验证 token ID 是否正确，以及该 token 是否已为您的组织启用。
法币不支持	`Unsupported fiat currency: {currency}`	使用支持的法币代码。请查阅 API 参考获取支持的值。
金额格式无效	`Invalid amount format: {amount}`	提供有效的十进制字符串，例如 `"10.50"`。请勿传入整数或科学计数法。
金额低于最低限额	消息中包含最低金额和 token 符号。	将金额增加至不低于错误信息中显示的最低阈值。
银行账户未找到	`Bank Account with account_uuid: {id} not found.`	验证 `bank_account_id` 值是否正确，且属于您的组织。
银行账户未获批准	`Bank account {id} is not approved.`	确保银行账户已完成验证和审批后再在请求中使用。
OTC 钱包未找到	`Wallet {wallet_id} unsupported or not found.`	验证 `wallet_id` 值。并非所有钱包类型都支持 OTC 兑换。
收款地址无效	`Invalid receiving address.`	检查目标地址格式，并确认其与指定的 token 和链兼容。
OTC 余额不足	消息描述了余额缺口。	在提交兑换请求前检查可用的 OTC 余额。
OTC 金额低于最低限额	消息中包含最低金额。	将兑换金额增加至错误信息中显示的最低限额以上。
OTC 汇率不可用	`Exchange rate for token {token_id} not found.`	重试请求。如果错误持续，该 token 可能不支持 OTC 兑换。
OTC 兑换未找到	`Conversion {conversion_code} not found.`	验证兑换代码或 OTC 订单 ID 是否正确。

认证与权限错误

错误码	HTTP 状态码	描述	解决方案
2001	400	执行此操作前需要完成 MFA 验证。	在 Cobo Portal 中完成 MFA 验证，然后重试请求。
4001	403	禁止访问请求的资源。	检查与您的 API Key 关联的权限。详情请参见角色与权限。
4002	400	您的组织状态不允许执行此操作。您的开发者账户可能尚未完成激活或处于审核中。	确认您的开发者入驻流程已全部完成。如问题持续，您的账户可能受到限制——请查看 Cobo Portal 中的相关通知。
10000	400	您的组织在 Cobo Portal 中具有只读权限，无法执行写操作。	请联系您的组织管理员，在 Cobo Portal 中审查账户权限。

配额与资源限制错误

错误码	HTTP 状态码	描述	解决方案
3000	400	您已用完所有可用的测试代币领取次数。测试代币 faucet 每个组织限领 10 次。	测试代币领取次数限制无法增加。请使用已有的测试代币继续测试。

转账与交易错误

以下错误码在发起转账、结算或提现时返回。

错误码	HTTP 状态码	描述	解决方案
30001	400	重复的 `request_id`。此 `request_id` 已在之前的请求中使用过。	每个请求必须使用唯一的 `request_id`。如果您正在重试请求，请复用相同的 `request_id` 以获取原始结果，而不是生成新的 `request_id`。
30002	400	未知的 token ID。指定的 token 无法识别。	根据支持的 token 列表验证 token ID。调用获取支持的 token 列表以获取您组织的有效 token ID。
30005	400	地址格式无效或与指定 token 不兼容。	验证目标地址对于该 token 所在网络的格式是否正确。确认地址属于正确的链。
30007	400	无效金额。金额值不是有效的数字。	提供有效的数值金额。确保不传入字符串、null 或科学计数法表示的值。
30009	400	金额不能小于零。	请提供正数金额值。
30010	400	转账金额低于最低提现阈值。`error_message` 字段包含最低金额和 token 符号。	将转账金额增加至不低于错误信息中显示的最低阈值。
30012	400	转账金额超出源钱包的可用余额。	在提交转账前检查钱包余额。减少转账金额或向钱包充值。
30013	400	手续费 token 余额不足以支付交易手续费。	在 Cobo Portal 的 Fee Station 下检查 Fee Station 余额，如有需要请充值。
30019	400	交易被链上交易策略拒绝。	在 Cobo Portal 中检查为您的智能合约钱包配置的链上交易策略。调整策略或使用其他钱包。
30024	400	未提供 `to_address` 或 `to_wallet_id`，两者中至少需要提供一个。	在请求中包含 `to_address` 或 `to_wallet_id` 中的一个。
30028	400	`request_id` 参数缺失或格式错误。	在请求中包含有效的 `request_id`。该值必须为非空字符串。
30030	400	此 token 的提现和充值服务暂时不可用。	查看 Cobo 状态页面了解当前服务公告。等待暂停解除后重试。
30031	400	该 token 未在您的组织中启用。	调用获取支持的 token 列表，验证该 token 是否对您的账户可用。如果列表中没有该 token，则表示该 token 尚未为您的组织激活。
30036	400	Fee Station 余额不足，无法支付本次交易的手续费。	向您的 Fee Station 充入支持的代币（例如 USDT 或 USDC），确保余额足以支付手续费，然后重试。
30038	400	Fee Station 中的 token 余额不足，无法支付本次交易的手续费。	向您的 Fee Station 充入支持的代币（例如 USDT 或 USDC），确保余额足以支付手续费，然后重试。
30039	400	Cobo 的 Fee Station 余额暂时不足。	短暂等待后重试。此问题由 Cobo 自动处理。

交易操作错误

以下错误码在取消、丢弃或加速现有交易时返回。

错误码	HTTP 状态码	描述	解决方案
60003	400	交易手续费估算失败。	重试手续费估算。如果错误持续，请验证 token 和钱包配置是否正确。
60004	400	此交易无法取消。	只有处于待处理或处理中状态的交易才能取消。在尝试取消之前检查交易状态。
60005	400	当前交易状态不允许取消操作。	交易已进入无法取消的阶段。在 Cobo Portal 中检查交易状态。
60006	400	此交易无法丢弃。	丢弃操作仅适用于特定类型和状态的交易。在 Cobo Portal 中查看交易详情。
60007	400	此交易无法加速。	加速操作仅适用于特定类型和状态的交易。在 Cobo Portal 中查看交易详情。

HTTP 状态码

状态码	描述	解决方案
200	成功。	不适用
400	错误请求。	检查请求参数。
401	未经授权。	检查 API Key、API 签名或时间戳。
403	禁止访问。	确保您具有所需权限。
404	未找到。	检查请求 URL。
405	方法不允许。	使用支持的 HTTP 方法。
406	不可接受。	确保请求内容格式为 JSON。
429	请求过多。	降低请求频率并稍后重试。
500	内部服务器错误。此错误可能由多个问题引起。	检查您的服务器配置设置并稍后重试。
502	错误网关。	检查连接并稍后重试。
503	服务不可用。	稍后重试。

概览

初始配置

收款

资金管理

索引信息

错误码

通用 API 错误

支付资源错误

认证与权限错误

配额与资源限制错误

转账与交易错误

交易操作错误

HTTP 状态码

​错误码

​通用 API 错误

​支付资源错误

​认证与权限错误

​配额与资源限制错误

​转账与交易错误

​交易操作错误

​HTTP 状态码

错误码

通用 API 错误

支付资源错误

认证与权限错误

配额与资源限制错误

转账与交易错误

交易操作错误

HTTP 状态码