> ## Documentation Index > Fetch the complete documentation index at: https://cobo.com/payments/llms.txt > Use this file to discover all available pages before exploring further. # 错误码与状态码 本文介绍了在使用 Cobo Payments API 时可能遇到的常见错误码和 HTTP 状态码，以及如何解决这些错误。 当请求失败时，响应体中包含 `error_code` 字段（整数）、描述问题的 `error_message` 字段，以及可用于在 Cobo 日志中追踪请求的 `error_id` 字段。 ### 错误码 #### 通用 API 错误 | 错误码 | HTTP 状态码 | 描述 | 解决方案 | | ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2006 | 400 | 一个或多个参数格式无效或包含不支持的值。 | 根据 [API 参考](/payments/cn/api-references/overview)验证请求体。检查参数类型、枚举值以及所有必填字段。`error_message` 字段通常会指明验证失败的具体参数。 | | 2010 | 429 | 您已超出 API 访问频率限制。 | 降低请求频率。在重试前实施指数退避加抖动策略。 | | 2024 | 401 | API Key 认证失败。 | 详情请参见[发送首个请求](/payments/cn/developer-tools/get-started-with-api)。 | | 2025 | 403 | 您的 API Key 没有执行此操作所需的权限。 | 在 Cobo Portal 中检查 API Key 的 OAuth scope 和角色分配。详情请参见[角色与权限](/payments/cn/guides/roles-and-permissions)。 | | 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 关联的权限。详情请参见[角色与权限](/payments/cn/guides/roles-and-permissions)。 | | 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 列表](/payments/cn/api-references/overview)以获取您组织的有效 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 列表](/payments/cn/api-references/payment/list-supported-tokens)，验证该 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 | 服务不可用。 | 稍后重试。 |