> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # 错误码 > 查阅 Account Center API 返回的错误码，了解它们出现在哪些场景，以及遇到时的处理方式。 当 Account Center API 调用失败时，网关会返回一个非 2xx 的 HTTP 状态码以及一段 JSON 错误体。用本页可以识别具体出错原因并决定恢复策略。

错误响应格式

Account Center API 对所有错误使用统一的响应信封： ```json theme={null} { "code": 400, "message": "Legal business name in English is required" } ``` | 字段 | 含义 | | --------- | ------------------------------------------------------------------------------------------------------------------------- | | `code` | 数值型状态码。多数情况下与响应的 HTTP 状态码相同。`400` 表示校验失败或业务规则冲突；`403` 表示认证 / 授权失败；`404` 表示路由不存在；`405` 表示 HTTP 方法不支持；`500` 表示幂等中间件的基础设施故障。 | | `message` | 人类可读的描述。可以安全记录到日志，但不宜原样展示给终端用户。相同 `code` 下需要靠 `message` 区分具体场景。 | 响应里没有 `type` 字段，也没有字符串形式的错误码 —— 一切都是数值 `code` 加 `message`。

错误码总览

| `code` | HTTP | 出现场景 | | ------ | ---- | ------------------------------------------------------------- | | `400` | 400 | 校验失败、业务规则冲突、JSON 格式错误，或任何 handler 层错误。根据 `message` 区分具体场景。 | | `403` | 403 | 认证失败 —— Access Token 缺失、格式错误或已过期；IP 白名单校验未通过；缺少 client id 声明。 | | `404` | 404 | 请求路径没有匹配到任何已注册的路由。 | | `405` | 405 | 请求路径合法，但 HTTP 方法未在该路径上绑定。 | | `500` | 500 | 幂等中间件内部故障（Redis / DB）。可以用相同的 `X-Idempotency-Key` 重试。 |

通用错误

以下错误可能出现在任何需要认证的接口上，与具体资源无关。 | `code` | 错误消息 | 处理方式 | | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `403` | Authorization error | 在请求中携带 `x-auth-token` 头，值是从 **Access Token** 接口取到的未过期 Access Token。如果 Token 已过期，重新签发后再重试。 | | `403` | x-client-id or email cannot be empty | 在 `x-client-id` 头里传入与调用 **Access Token** 时相同的 `client_id`。认证请求不得省略该头。 | | `400` | IP not allowed | 确认请求来源 IP 在开发者密钥的白名单内。在 UQPAY 控制台更新白名单，或改用允许的 IP 发起重试。 | | `400` | Request parameters invalid | 对照该接口的 API Reference 重新检查请求体和查询参数 —— 很可能是必填字段缺失或类型错误。 | | `400` | *（内容不固定 —— 原始 JSON 绑定 / 校验器报错文本，例如 `Field 'X' is required`、`Invalid type for field 'X'`）* | 直接阅读 `message`：它会指出出错的字段以及未通过的校验规则。修正请求体中的该字段后重试。 | | `400` | access token err | `x-auth-token` 缺失、格式错误，或 JWT claims 无法解析出对应的实体。从 **Access Token** 接口重新签发一个 Token 后重试。 | | `400` | Idempotency key error | 提供合法的 `X-Idempotency-Key` —— 2024-08-15 之后创建的账户要求是 RFC-4122 UUID；更早的账户可以是 1–36 位字符串。不要复用已过期的键。 | | `400` | Idempotency key auth error | 你提交的 `X-Idempotency-Key` 已经被另一个实体使用过。每次请求生成新的 UUID，或改用原始调用方的凭证重试。 | | `400` | Idempotency endpoint error | 该 `X-Idempotency-Key` 之前被用在了另一个接口上。每个接口使用独立的键，或对原接口重新发起请求。 | | `400` | Request is processing, please try again later. *（响应体里的 `code` 是 200）* | 原始请求还在执行中。等几秒后用同一个 `X-Idempotency-Key` 再次请求，就能拿到缓存响应。 | | `500` | An internal error occurred, please try again later *（响应体没有 `code` 字段）* | 幂等中间件（Redis / DB）的临时故障。可以用同一个 `X-Idempotency-Key` 重试；若持续出现，请联系 UQPAY 支持。 | | `401` | Invalid authorization header *（响应以 `{ "error": ... }` 形式返回）* | `x-auth-token` 以 `Bearer ` 开头，但不是合法的 `Bearer ` 组合。要么去掉 `Bearer ` 前缀只传原始 JWT，要么严格按 `Bearer ` 格式传（中间只能有一个空格）。 | | `404` | Not found | 对照 API Reference 检查请求路径和 HTTP 方法 —— 你调用的路由没有在网关上注册。 | | `405` | Method not allowed | 路径是合法的，但 HTTP 方法用错了。在 API Reference 中确认该接口对应的动词（GET / POST / PUT / DELETE）。 |

资源类错误

认证

Access Token `POST /v1/connect/token` 使用独立的 handler（`AccessHandler.AccessToken`），**只**会返回扁平的 HTTP 400 响应 —— 包括 API 密钥过期或不存在之类的认证相关失败。`message` 会告诉你具体原因。 | `code` | 错误消息 | 典型接口 | 处理方式 | | ------ | -------------------------- | ------------ | --------------------------------------------------------------------------------------- | | `400` | Request parameters invalid | Access Token | 在向 `/v1/connect/token` 发起 POST 时，同时提供非空的 `client_id` 和 `api_key`（表单字段或 JSON body 字段均可）。 | | `400` | Invalid client id | Access Token | 确认 `client_id` 与 UQPAY 控制台中某个开发者凭证完全一致。重新复制一次以排除多余空白或拼写错误。 | | `400` | Invalid api key | Access Token | 确认 `api_key` 与 `client_id` 配对的密钥一致。如果密钥已轮换，请在控制台重新生成一对并更新集成。 | | `400` | Api key expired | Access Token | 你的 `api_key` 已超过有效期。在 UQPAY 控制台生成新的密钥对，并更新到集成中。 | | `400` | Entity config not exist | Access Token | 该 `client_id` 所属实体尚未配置访问画像。联系对接你的 UQPAY 解决方案工程师，为该实体开通配置。 | | `400` | Api trading status error | Access Token | 开发者密钥被禁用，或该实体的交易状态不可用。在 UQPAY 控制台检查密钥状态，或联系 UQPAY 支持恢复。 | | `400` | IP not allowed | Access Token | 调用方 IP 不在该 `api_key` 的白名单内。在 UQPAY 控制台添加 IP，或改用允许的 IP 发起重试。 | | `400` | Create access token error | Access Token | 内部签名 / 持久化失败。稍后重试；若持续出现，请联系 UQPAY 支持。 |

实体

Create Account · Create SubAccount · List Connected Accounts · Retrieve Account · Get Additional Documents 账户创建请求的校验非常严格（`Create Account` 和 `Create SubAccount` 合计有 80 多条字段级错误消息），全部以扁平 HTTP 400 返回，`message` 就是原始的校验器文本。下面列的是代表性场景 —— 编程处理时请根据 `message` 分支判断。 | `code` | 错误消息 | 典型接口 | 处理方式 | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ | | `400` | access token err | 本组任一接口 | `x-auth-token` 缺失，或其 claims 无法解析出调用方实体。从 **Access Token** 接口重新签发 Token 后重试。 | | `400` | entity not exist | Retrieve Account | 确认 `{id}` 路径参数指向的是你凭证可见的账户。用 **List Connected Accounts** 列出你可访问的全部账户。 | | `400` | unable to retrieve the corresponding entityinfo | Retrieve Account | `{id}` 存在，但未作为父账户 / 子账户挂在你的调用实体下。在检索前先确认该账户属于你的层级。 | | `400` | entity not found | Retrieve Account | `{id}` 没有对应的任何账户记录。请重新核对 ID —— 它应该是 **List Connected Accounts** 返回过的值。 | | `400` | *（字段校验 —— 内容不固定，例如 `Legal business name in English is required`、`Country or territory is required`、`Invalid phone number format`、`Individual must be over 18 years old`、`Job title is required and must be one of director, beneficial_owner, beneficial_owner_and_director, authorized_representative`、`Entity type is required and must be one of COMPANY, INDIVIDUAL`）* | Create Account · Create SubAccount | 直接阅读 `message` —— 它会指出出错字段及违反的规则。在请求的 `business_details` / `identities` / `owners` 里修正对应字段后重试。 | | `400` | The country is not allowed to be used for onboarding | Create Account · Create SubAccount | `business_details.country` 或 `identities[].country` 中填的国家不在 UQPAY 支持范围内。换一个支持的司法辖区，或联系 UQPAY 支持确认扩展计划。 | | `400` | The country is a sanctioned country | Create Account · Create SubAccount | UQPAY 无法在受制裁的司法辖区入驻账户。更换国家 —— 用同样的国家重试不会成功。 | | `400` | please check whether the master account has opened the corresponding service | Create Account · Create SubAccount | 你的主账户未开通该请求隐含的产品权限（Acquiring / Banking / Issuing）。联系对接你的 UQPAY 解决方案工程师开通相应服务。 | | `400` | please check whether the master account has opened the create sub account service | Create SubAccount | 你的主账户没有子账户开通权限。联系 UQPAY 开通后再重试。 | | `400` | please completed the verification and activate your account first | Create Account · Create SubAccount | 你的主账户仍处于 KYC / 激活流程中。先完成主账户的入驻流程，再创建子账户。 | | `400` | only banking can create individual account | Create Account · Create SubAccount | 个人（非企业）账户只能在 Banking 产品下创建。把实体类型改为 `COMPANY`，或申请 Banking 的个人入驻权限。 | | `400` | failed to retrieve account configuration | Create Account · Create SubAccount | 内部查询失败。稍后重试；若持续出现，请联系 UQPAY 支持。 | | `400` | failed to retrieve parent account related info | Create SubAccount | 父账户的内部查询失败。确认调用方 Token 属于合法的主账户，然后重试。 | | `400` | failed to check sub account limit | Create SubAccount | 子账户限额的内部校验失败。稍后重试；若持续出现，请联系 UQPAY 支持。 | | `400` | *（内容不固定 —— 例如 `same UEN sub account limit reached, current: 10, max: 10`）* | Create SubAccount | 同一 UEN / 注册号下的子账户数量已达上限。整理现有子账户，或联系 UQPAY 提升上限。 | | `400` | Company info, address, and ownership details are required when Inherit is false | Create SubAccount | 要么把 `inherit` 设为 `true` 来复用父账户的 KYC 数据，要么完整提供 `business_details`、`address`、`owners` 区块。 | | `400` | Please check that you have correctly specified inherit | Create SubAccount | `inherit` 标志与请求体其他内容不一致。继承场景下设为 `true`；不继承则设为 `false` 并补齐完整企业信息。 | | `400` | representatives is empty | Create Account · Create SubAccount | `representatives` / `identities` 数组至少需要一条 —— UQPAY 要求必须有一位具名的授权代表。 | | `400` | representative identification documents are empty | Create Account · Create SubAccount | 每位代表都需要通过 **Upload A File** 上传身份证件（护照 / 国民身份证），并在代表记录中引用返回的文件 ID。 | | `400` | one representative must be an applicant | Create Account · Create SubAccount | 请求中需要恰好有一位代表被标记为申请人（`is_applicant: true`，或角色为 `authorized_representative`）。 | | `400` | Failed identification, at least one beneficiary submitted front and back identification photos and face photos | Create Account · Create SubAccount | 至少有一位受益人需要通过 **Upload A File** 上传证件正面、反面和人脸照片，并在该受益人记录中引用这三个文件 ID。 | | `400` | document ID already exists | Create Account · Create SubAccount | 你提交的证件号码已与 UQPAY 系统中另一个实体绑定。换用正确的实体，或联系 UQPAY 支持解决冲突。 | | `400` | check that you have submitted the necessary documents | Create Account · Create SubAccount | 所需资料缺失一项或多项 —— 具体清单因实体类型和国家而异。参考你的 UQPAY 入驻清单，通过 **Upload A File** 补齐缺失资料。 | | `400` | businessDetails is nil | Create Account · Create SubAccount | 请求体缺少 `business_details` 对象。请补上（子账户场景可以设 `inherit: true` 从父账户继承）。 | | `400` | entityBasicVersion is nil | Create Account · Create SubAccount | 父账户记录的内部状态存在问题。请携带请求 ID 联系 UQPAY 支持 —— 原样重试大概率仍会失败。 | | `400` | entity is nil | Create Account · Create SubAccount | 服务端无法解析出调用方实体。从 **Access Token** 接口重新签发 Access Token 后重试；若持续出现，请联系 UQPAY 支持。 | | `400` | server error | Create Account · Create SubAccount | 内部故障。稍后重试是安全的；若持续出现，请携带请求 ID 联系 UQPAY 支持。 | | `400` | *（通用持久化失败 —— 原始数据库或序列化错误被服务层包裹后的文本）* | Create Account · Create SubAccount | 完整记录 `message` 内容并联系 UQPAY 支持 —— 被包裹的错误文本能定位出哪一步持久化失败。原样重试大概率仍不会成功。 |

文件

Upload A File · Get File Download Links | `code` | 错误消息 | 典型接口 | 处理方式 | | ------ | ------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `400` | access token err | Upload A File · Get File Download Links | `x-auth-token` 缺失或无法解析。从 **Access Token** 接口重新签发 Token 后重试。 | | `400` | x-on-behalf-of value err | Upload A File · Get File Download Links | `x-on-behalf-of` 头的值必须是当前主账户下某个子账户的实体 ID。通过 **List Connected Accounts** 核对；如果想针对主账户自身操作，直接不传这个头即可。 | | `400` | Request parameters invalid | Upload A File · Get File Download Links | 检查必填字段 —— **Upload A File** 需要 multipart 中的 `file` 部分；**Get File Download Links** 需要 JSON body 中的 `file_ids` 数组。 | | `400` | Parse file failed | Upload A File | multipart 表单解析失败。确认请求使用 `Content-Type: multipart/form-data`、包含 boundary，且文件字段名为 `file`。 | | `400` | File size error *（阈值：30 MiB）* | Upload A File | 文件超过 30 MiB。上传前先压缩或拆分文件。 | | `400` | invalid file name, please check the file | Upload A File | 上传文件的文件名为空或后缀不支持。请提供有效文件名并使用支持的扩展名（`.jpeg`、`.png`、`.jpg`、`.doc`、`.docx`、`.pdf`）。 | | `400` | invalid file type, please check the file, only support jpeg, png, jpg, doc, docx, pdf | Upload A File | 转换为支持的格式之一（JPEG / PNG / JPG / DOC / DOCX / PDF）后重试。 | | `400` | unsupported file type | Upload A File | 文件的 MIME 类型不在支持列表内。重新导出为 JPEG / PNG / PDF / DOC / DOCX 后重试。 | | `400` | *（内容不固定 —— 例如 `file validation failed: mime type mismatch`）* | Upload A File | 直接阅读 `message` —— 它会指出未通过的校验规则（最常见是 MIME 类型与扩展名不匹配）。重新导出文件后再重试。 | | `400` | open file occur error, please check the file | Upload A File | 服务器无法打开上传的文件 —— 通常是因为传输中被截断或损坏。重新选择源文件后重新上传。 | | `400` | read file occur error, please check the file | Upload A File | 上传的文件流无法读取。使用原始源文件重试；若持续出现，文件可能已损坏。 | | `400` | seek file error | Upload A File | 处理上传时出现内部 I/O 错误。重试即可；若持续出现，请联系 UQPAY 支持。 | | `400` | upload file occur error, please contact our team | Upload A File | 云存储写入失败。稍后重试；若持续出现，请携带请求 ID 联系 UQPAY 支持。 | | `400` | Query data error | Get File Download Links | 某个或多个 `file_ids` 不存在，或对你的实体不可见。请核对 ID —— 它们必须来自你的凭证能访问的 **Upload A File** 返回结果。 |

幂等

Create Account · Create SubAccount · Upload A File 幂等中间件会作用在每一个带 body 的 `POST` 请求上。一旦识别出是重放请求，就会在 handler 执行前短路返回。 | `code` | 错误消息 | 典型接口 | 处理方式 | | ------ | -------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `400` | Idempotency key error | Create Account · Create SubAccount · Upload A File | 提供合法的 `X-Idempotency-Key` —— 2024-08-15 之后创建的实体要求是 RFC-4122 UUID；更早的实体可以是 1–36 位字符串。不要复用超过 24 小时的键。 | | `400` | Idempotency key auth error | Create Account · Create SubAccount · Upload A File | `X-Idempotency-Key` 已缓存在另一个实体名下。每次请求生成新的 UUID，或改用原始调用方的凭证重试。 | | `400` | Idempotency endpoint error | Create Account · Create SubAccount · Upload A File | 同一个 `X-Idempotency-Key` 之前被用在了另一个接口上。每个接口使用独立的键，或对原接口重新发起请求。 | | `200` | Request is processing, please try again later. *（HTTP 状态是 400，响应体 `code` 是 200）* | Create Account · Create SubAccount · Upload A File | 原始请求还在执行中。等几秒后用同一个 `X-Idempotency-Key` 重试 —— 处理完成后会返回缓存响应。 | | *（无）* | An internal error occurred, please try again later *（HTTP 500，响应体没有 `code` 字段）* | Create Account · Create SubAccount · Upload A File | 幂等层的临时基础设施故障。用同一个 `X-Idempotency-Key` 重试即可；若持续出现，请联系 UQPAY 支持。 |