错误处理
接口失败时，先不要猜原因。按这个顺序看：
- 看 HTTP 状态码：
401是认证问题，403是权限问题，400多半是参数问题。 - 看返回里的
message：它会告诉你具体错在哪个字段或哪个配置。 - 按下面的表格处理：先修请求参数，再检查账号/API Key/路由配置。
成功响应通常是：
{
"code": 0,
"message": "ok",
"data": {}
}
失败响应通常是：
{
"code": 53,
"message": "payout route not configured",
"data": null
}
快速判断
| HTTP 状态 | 常见含义 | 先检查什么 |
|---|---|---|
400 | 请求参数不对，或业务配置不匹配 | 请求字段、金额、币种、收款人、出金路由 |
401 | 没有认证成功 | API Key、Bearer Token、IP 白名单 |
403 | 已认证，但没有权限 | API Key 权限、账号是否开通对应产品 |
404 | 资源不存在或当前账号看不到 | payout_id、order_id、batch_id、环境是否正确 |
500 | 平台或上游服务异常 | 先查询订单状态，不要盲目重复提交 |
返回字段
| 字段 | 说明 |
|---|---|
code | 业务分类码。0 表示成功；失败时主要用来区分大类 |
message | 最重要的排查信息。下面的错误列表按这个字段整理 |
data | 成功数据；失败时通常为空或包含补充信息 |
常见业务码：
code | 含义 |
|---|---|
0 | 成功 |
51 | 基础参数校验失败，例如必填字段没传、长度不对 |
53 | 业务参数或业务配置不正确 |
61 | 认证或权限失败 |
65 | 资源不存在 |
50 | 平台内部或上游异常 |
认证与权限错误
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
unauthorized | 没有传 token，token 格式不对，或 token 无效 | 请求头传 Authorization: Bearer <token>，或传 X-API-Key: <token>；确认 token 是完整复制的 |
api key not found | API Key 不存在，或你把 Sandbox / Live 环境用错了 | 重新创建 API Key，并确认请求地址和 Key 是同一个环境 |
api key disabled | API Key 被禁用了 | 在商户后台启用，或 创建新的 API Key |
api key expired | API Key 已过期 | 创建或续期 API Key |
api key version mismatch | API Key 已轮换，旧 token 不能再用 | 使用最新 token |
invalid api key token | token 内容不完整或格式异常 | 重新复制完整 token，不要手动改 token |
ip not allowed | 当前服务器出口 IP 不在白名单里 | 把你的服务器出口 IP 加到 API Key 白名单 |
ip not allowed: <ip> | 返回的 <ip> 就是平台识别到的请求来源 IP | 把这个 <ip> 加到 API Key 白名单 |
forbidden | API Key 没有接口权限，或账号未开通该产品 | 给 API Key 加权限；确认账号已开通收单/出金等产品 |
常见权限：
| 你要做的事 | 需要的权限 |
|---|---|
| 查询账号 | payment.account.read |
| 查询余额 | payment.wallet.read |
| 查询流水 | payment.ledger.read |
| 创建 Quick Payout / 出金单 | payment.payout.create |
| 查询出金单 | payment.payout.read |
| 更新出金单 | payment.payout.update |
| 提交出金单 | payment.payout.submit |
| 取消出金单 | payment.payout.cancel |
| 管理收款人 | payment.payout.beneficiary.read / payment.payout.beneficiary.write |
| 管理收款账户 | payment.payout.beneficiary_account.read / payment.payout.beneficiary_account.write |
通用请求错误
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
Validation Failed | 字段没通过基础校验，例如必填、长度、枚举值、最小值 | 对照接口参数表修正字段 |
request required | 请求体为空，或 JSON 没有被正确解析 | 设置 Content-Type: application/json，发送合法 JSON |
<field> required | 某个必填字段没传 | 补上提示里的字段，例如 currency、reference、payout_id |
invalid notify_url | 回调地址格式不合法 | 使用完整地址，例如 https://merchant.example.com/webhooks/payout |
invalid status | 状态筛选值不支持 | 使用文档里的状态值 |
invalid review_status | 审核状态筛选值不支持 | 使用 draft、pending_review、returned、rejected、approved |
invalid execution_status | 执行状态筛选值不支持 | 使用 init、processing、completed、failed、cancelled |
no changes | 更新接口没有传任何要修改的字段 | 至少传一个要修改的字段 |
account not found | token 对应账号不存在，或当前环境不对 | 检查 API Key 和请求环境 |
account frozen | 商户账号被冻结 | 联系 Beyounger 处理账号状态 |
internal error | 平台隐藏了内部错误细节 | 保存请求时间、接口路径、请求参数和返回内容，联系 Beyounger |
法币出金错误
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
currency required | 没传出金币种 | 传 currency，例如 USD |
currency not supported | 当前账号不支持这个币种 | 确认账号已开通该币种 |
amount must be greater than zero | 金额必须大于 0 | 传大于 0 的金额 |
amount must be greater than fee when fee_bearer is user | 手续费由收款人承担时，金额不够扣手续费 | 增加金额，或改成 fee_bearer: merchant |
fee_bearer must be merchant or user | 手续费承担方写错了 | 只能传 merchant 或 user |
reference required | 没传商户订单号/业务参考号 | 传唯一的 reference |
reference already exists | 这个 reference 已经创建过出金单 | 先查询原出金单，不要重复创建 |
beneficiary_account_id required | 没传已有收款账户，也没传 inline 收款信息 | 传 beneficiary_account_id，或同时传 beneficiary 和 beneficiary_account |
beneficiary and beneficiary_account must be provided together | 只传了收款人或只传了收款账户 | 两个对象必须一起传 |
method_id required when creating beneficiary inline | inline 创建收款人时没传出金方式 | 传 method_id |
channel_id requires method_id | 传了 channel_id，但没传 method_id | 同时传对应的 method_id |
method_id required when channel_id provided | 传了 channel_id，但没传 method_id | 同时传对应的 method_id |
payout method not found | 出金方式不存在或当前商户不可用 | 确认 method_id，或让 Beyounger 开通该方式 |
payout channel not found | 出金通道不存在或未给当前商户配置 | 不确定时不要传 channel_id；联系 Beyounger 确认路由 |
payout route not configured | 当前账号、币种、方式、金额没有匹配到可用路由 | 联系 Beyounger 配置出金路由 |
channel account not configured | 路由有了，但通道账号没配好 | 联系 Beyounger 配置通道账号 |
payout method not supported for currency type | 法币/加密货币方式用错了 | 法币出金用 fiat 方法，加密货币出金用 crypto 方法 |
beneficiary account not found | 收款账户不存在，或不属于当前账号 | 检查 beneficiary_account_id |
beneficiary account not active | 收款账户不是启用状态 | 启用或重新创建收款账户 |
beneficiary account disabled, please enable it first | 收款账户被禁用 | 先启用收款账户 |
beneficiary account suspended | 收款账户被挂起 | 联系 Beyounger，或换一个收款账户 |
beneficiary account type mismatch | 收款账户类型和币种/通道不匹配 | 不确定时不要传 account_type |
account_type mismatch | 传入的 account_type 不符合通道要求 | PayPal 场景通常不要传 account_type: paypal |
beneficiary not found | 收款人不存在，或不属于当前账号 | 检查 beneficiary_id |
beneficiary disabled | 收款人被禁用 | 启用或重新创建收款人 |
beneficiary method mismatch | 收款人绑定的方式和本次请求的 method_id 不一致 | 使用一致的 method_id，或重新创建收款人 |
beneficiary channel mismatch | 收款人绑定的通道和本次请求的 channel_id 不一致 | 使用一致的通道，或不要传 channel_id |
beneficiary account mismatch | 收款人和收款账户不是一组 | 使用同一收款人下的收款账户 |
beneficiary profile incomplete: missing <fields> | 通道要求更多收款人资料 | 补齐 <fields> 中列出的字段 |
wallet not found | 当前账号没有对应币种的钱包 | 联系 Beyounger 开通钱包 |
merchant account not found | 当前账号配置不完整 | 联系 Beyounger 检查账号配置 |
payout not found | 出金单不存在，或不属于当前账号 | 检查 payout_id 和环境 |
payout not editable | 出金单已经不能修改 | 先查询状态，不要继续更新 |
payout already approved | 出金 单已经审核通过 | 等待执行结果，或查询状态 |
payout already processing | 出金单已经在执行中 | 等待 webhook 或调用查询接口 |
payout rejected | 出金单已被拒绝 | 修正信息后创建新的出金单 |
invalid payout status | 当前状态不允许这个操作 | 先查询出金单状态，再决定下一步 |
收款人字段错误
这些错误通常出现在 beneficiary.fields。
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
beneficiary fields required | 没传收款人字段 | 传 beneficiary.fields |
fields required | 没传字段对象 | 传 fields |
fields missing required: <fields> | 少了必填字段 | 补齐 <fields> 中列出的字段 |
fields.payee_id invalid: expect ^[a-zA-Z0-9]{3,60}$ | payee_id 只能是 3-60 位字母或数字 | 改成符合规则的 ID |
fields.language invalid: expect 2 letters | 语言格式错误 | 传两位字母，例如 en |
fields.country invalid: expect ISO-2 uppercase | 国家格式错误 | 传 ISO-2 大写国家码，例如 US |
fields.phone invalid: expect (\\+[0-9]{1,3}-)?[0-9]{4,12} | 手机号格式错误 | 用 +1-4155550100，或 4-12 位纯数字 |
fields.birthdate invalid: expect yyyy-MM-dd | 出生日期格式错误 | 用 1990-01-31 |
fields.email invalid | 邮箱格式错误 | 传合法邮箱 |
fields.first_name invalid: length 3-100, letters/'/-/space only | 名字长度或字符不符合规则 | 使用 3-100 位字母、空格、' 或 - |
fields.last_name invalid: length 3-100, letters/'/-/space only | 姓氏长度或字符不符合规则 | 使用 3-100 位字母、空格、' 或 - |
fields.zip invalid: length 3-30 | 邮编长度不对 | 按收款人国家填写邮编 |
fields.zip invalid for country <country> | 邮编格式和国家不匹配 | 按 <country> 的邮编规则修改 |
fields.city invalid: length 2-120 | 城市长度不对 | 传 2-120 个字符 |
fields.state invalid: length 2-60 | 州/省长度不对 | 传 2-60 个字符 |
fields.address invalid: length 3-200 | 地址长度不对 | 传 3-200 个字符 |
收款账户字段错误
这些错误通常出现在 beneficiary_account 或收款账户创建接口。
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
network_code required | 没传收款网络 | 传 beneficiary_account.network_code |
network not found | 网络不存在或当前商户不可用 | 先用 GET /payment/payout-networks 查询可用网络 |
schema required | 这个网络缺少字段配置 | 联系 Beyounger 检查网络配置 |
field <name> required | 收款账户缺少字段 | 按网络 schema 补齐字段 |
field <name> invalid | 收款账户字段格式不对 | 按网络 schema 的提示修改 |
field <name> invalid: <hint> | 字段格式不对，<hint> 是格式要求 | 按 <hint> 修改 |
unknown field <name> | 传了 schema 不认识的字段 | 删除这个字段 |
cashapp_account must start with $ | Cash App 账号必须以 $ 开头 | 例如 $example |
beneficiary account already exists | 相同收款账户已经存在 | 复用已有收款账户 |
加密货币批量出金错误
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
items required | 没传批量明细 | 传 items |
items length must be between 1 and 500 | 明细数量必须是 1-500 条 | 拆分批次或补充明细 |
only crypto currency supported | 批量加密出金不能传法币 | 使用加密货币币种 |
method_id required | 没传出金方 式 | 传 crypto 类型的 method_id |
payout method not supported for crypto | 传入的方式不是 crypto 出金方式 | 换成 crypto 出金方式 |
order_no required | 明细缺少商户订单号 | 每条明细传唯一 order_no |
duplicate order_no in request | 本次请求里有重复订单号 | 去重后再提交 |
duplicate order_no in batch | 批次里已有相同订单号 | 换新的 order_no |
duplicate order_no in merchant payouts | 历史出金里已经有这个订单号 | 查询原出金单，不要重复出金 |
beneficiary_account.address required | 收款地址为空 | 传收款地址 |
receiving address required | 收款地址为空 | 传收款地址 |
invalid EVM receiving address | EVM 地址格式错误 | 使用合法 EVM 地址 |
invalid TRON receiving address | TRON 地址格式错误 | 使用合法 TRON 地址 |
duplicate receiving address in batch request | 本次批次里收款地址重复 | 去重或拆分批次 |
batch not found | 批次不存在或当前账号看不到 | 检查 batch_id 和环境 |
batch not editable | 批次已经不能修改 | 查询批次状态 |
batch not ready for submit | 批次还不能提交 | 先修正批次明细 |
batch has no items | 批次没有明细 | 添加明细 |
batch not approved | 批次还没审核通过 | 等待审核结果 |
batch contains multiple payout channel accounts; split batch by route | 一个批次里混用了多个出金路由 | 按路由拆成多个批次 |
收单错误
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
order_currency only supports USD | 订单计价币种当前只支持 USD | 传 USD |
order_amount must be > 0 | 订单金额必须大于 0 | 传大于 0 的金额 |
expire_seconds must be between 60 and 10800 | 订单有效期必须在 60-10800 秒 | 修改过期时间 |
underpay_tolerance must be >= 0 | 少付容忍值不能是负数 | 传大于等于 0 的值 |
allowed_pay_currencies required | 没传允许支付的币种 | 传 allowed_pay_currencies |
notify_webhook_id required | 没传收单 webhook 配置 ID | 传有效的 notify_webhook_id |
notify_webhook_id invalid or inactive | webhook 不存在或未启用 | 在商户后台启用 webhook |
notify_webhook_id not subscribed to acquiring events | webhook 没订阅收单事件 | 给 webhook 订阅 acquiring.* |
redirect_url must be an absolute https URL or a same-origin relative path | 跳转地址格式不对 | 使用 HTTPS 完整地址，或同源相对路径 |
logo_url must be an absolute https URL | logo 地址必须是 HTTPS 完整地址 | 使用 HTTPS 图片地址 |
mode must be checkout or direct | 收单模式写错 | 传 checkout 或 direct |
unsupported checkout_type | checkout 类型不支持 | 使用已开通的 checkout 类型 |
network/currency required | 网络和币种没有同时传 | 同时传网络和币种 |
network/currency not allowed by order | 支付网络/币种不在订单允许范围内 | 使用订单允许的支付选项 |
unsupported network/currency: <network>/<currency> | 当前账号不支持这个网络/币种组合 | 换支付选项，或联系 Beyounger 开通 |
no available pay tokens for current account | 当前账号没有可用支付币种 | 联系 Beyounger 配置支付币种 |
order not found | 订单不存在或当前账号看不到 | 检查 order_id 和环境 |
completed order cannot be closed | 订单已经完成，不能关闭 | 按完成状态处理 |
checkout_url not found | hosted checkout 地址不存在 | 检查订单 ID 和订单模式 |
Webhook 接收错误
这些错误多出现在平台接收上游服务回调时。商户一般只需要保留日志，必要时联系 Beyounger。
你看到的 message | 是什么意思 | 你该怎么做 |
|---|---|---|
webhook ip not allowed | 回调来源 IP 不在白名单内 | 检查上游 IP 白名单配置 |
unsupported acquiring webhook provider: <provider> | 回调 provider 不支持 | 确认 provider 配置 |
empty cobo webhook event | Cobo 回调事件为空 | 保存原始回调内容 |
invalid cobo merchant deposit payload | Cobo 回调内容格式不对 | 保存原始 payload |
acquiring order not found | 回调无法匹配本地收单订单 | 检查上游订单号和本地订单 |
merchant deposit address not found | 回调地址无法匹配商户充值地址 | 检查充值地址配置 |
是否可以重试
| 错误类型 | 能不能直接重试 | 建议 |
|---|---|---|
401 / 403 | 不建议 | 先修 token、IP 白名单或权限 |
400 参数错误 | 不建议 | 先修请求参数 |
404 资源不存在 | 不建议 | 先确认 ID、账号和环境 |
查询接口 5xx | 可以 | 用退避重试，不要高频请求 |
创建/提交/打款接口 5xx | 谨慎 | 先用 reference、client_request_id 或 payout_id 查询状态，避免重复出金 |