# 响应码

> 对照账户服务响应信封、成功响应码和建议处理动作。

当账户服务响应返回非成功响应码时，可用本页定位错误类型、理解可能原因，并决定下一步排查动作。请始终以当前接口页面展示的响应字段名为准。

<note>

当前账户余额、账户流水和账户账单接口不使用 `code` / `message` 作为主响应信封。它们使用 `respCode` / `respMsg`，其中 `20000` 表示请求已成功处理。

</note>

## 当前账户服务接口

账户余额、账户流水接口使用 JSON 响应信封：`respCode` / `respMsg` / `data` / `error`。

账户账单导出接口成功时返回 CSV 文件流；只有在 CSV 响应尚未提交且请求失败时，才返回 JSON 错误响应，其中包含 `respCode`、`respMsg` 和 `error`。

| respCode | 默认 `respMsg` | 错误类型 | 中文说明 | 建议处理 |
| --- | --- | --- | --- | --- |
| `20000` | `Success` | - | 请求已成功处理。 | 继续读取当前接口的 `data` 字段、账户余额明细、账户流水记录或分页字段。账户账单导出成功时读取 CSV 文件流。 |
| `10001` | `Invalid request parameter` | `invalid_request_error` | 请求参数缺失、格式错误、超出允许范围，或传入了不支持的枚举值。 | 对照接口字段表检查必填字段、币种代码、枚举值、时间戳要求、查询时间范围和请求示例。 |
| `10006` | `DUPLICATE_REQUEST` | `idempotency_error` | `requestId` 在幂等窗口内重复使用。 | 先确认原请求的处理结果；只有发起全新操作时才生成新的 `requestId`。 |

`error` 对象用于承载标准化错误信息：

| 字段 | 说明 |
| --- | --- |
| `code` | 对外业务错误码，通常与 `respCode` 对齐。 |
| `declineCode` | 兼容字段，当前账户服务接口中通常与 `code` 保持一致。 |
| `message` | 可读错误信息。 |
| `type` | 标准化错误类型，例如 `invalid_request_error`、`idempotency_error` 或 `api_error`。 |
| `param` | 触发错误的请求参数名；仅在适用时返回。 |
| `requestId` | 调用方请求 ID，与请求 body 中的 `requestId` 保持一致。 |

## Global Account 接口

Global Account 创建与详情查询接口使用 `success` / `respCode` / `respMsg` 响应信封，成功响应码为 `20000`。

| respCode | Constant | 默认 `respMsg` | 中文说明 | 建议处理 |
| --- | --- | --- | --- | --- |
| `20000` | `SUCCESS_CODE` | `Success` | 请求已成功处理。 | 继续读取当前接口的 `data` 字段和 Global Account 状态值。 |
| `10001` | `INVALID_PARAMETER` | `Invalid request parameter` | 请求参数缺失、格式错误、超出允许范围，或传入了不支持的枚举值。 | 对照接口字段表检查必填字段、枚举值、查询约束和请求示例；详情查询时 `globalAccountId` 必须为数字格式，且 `globalAccountId` 与 `globalAccountNo` 至少传入一个。 |
| `10002` | `INVALID_TIME_RANGE` | `Invalid query time range` | 查询时间范围无效，或超过当前请求支持的范围。 | 按接口查询约束调整开始时间和结束时间后重试。 |
| `10003` | `UNAUTHORIZED_ACCESS` | `Access denied` | 调用方无权访问请求的账户服务资源或能力。 | 检查 `apikey`、环境、商户账户和 IP 白名单是否与目标资源匹配；如应已开通权限，请联系 Onerway 支持。 |
| `10004` | `RESOURCE_NOT_FOUND` | `Resource not found` | 请求的 Global Account 或关联业务资源不存在。 | 核对 `globalAccountId`、`globalAccountNo`、环境和商户归属关系；不要用同一标识盲目重试。 |
| `10005` | `REQUEST_FAILED` | `Request failed` | 账户服务未能完成本次请求。 | 结合响应 `respMsg` 和请求上下文排查；仅在操作可安全重复或已做幂等保护时重试。 |
| `10006` | `DUPLICATE_REQUEST` | `Duplicate request` | 请求与之前的请求重复，或使用了已经处理过的幂等标识。 | 先查询既有处理结果；只有发起全新操作时才使用新的 `requestId`。 |
| `10007` | `INIT_GLOBAL_ACCOUNT_FAILED` | `Init global account failed` | Global Account 初始化失败。 | 检查 `customerId`、`onBehalfOf`、支持币种、开户银行国家或地区以及账户能力配置；如果请求数据无误，请联系 Onerway 支持。 |
| `10008` | `GLOBAL_ACCOUNT_CUSTOMER_INVALID` | `Invalid customer id for global account` | 客户标识不能用于当前 Global Account 操作。 | 确认 `customerId` 属于当前商户账户；平台代子客户调用时，确认 `customerId` 与 `onBehalfOf` 一致且存在有效父子关系。 |
| `10009` | `GLOBAL_ACCOUNT_CALLER_NOT_AUTHORIZED` | `Caller identity does not match customer` | 调用方身份与 Global Account 资源关联的客户不匹配。 | 确认 `apikey`、商户账户、`customerId`、`onBehalfOf` 和 Global Account 标识属于同一授权关系。 |