错误码

当 Account Center API 调用失败时，网关会返回一个非 2xx 的 HTTP 状态码以及一段 JSON 错误体。用本页可以识别具体出错原因并决定恢复策略。

错误响应格式

Account Center API 对所有错误使用统一的响应信封：

{
  "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 <token>` 组合。要么去掉 `Bearer` 前缀只传原始 JWT，要么严格按 `Bearer <jwt>` 格式传（中间只能有一个空格）。
`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 支持。

入门

认证

账户管理

Webhooks

参考

错误响应格式

错误码总览

通用错误

资源类错误

认证

实体

文件

幂等

​错误响应格式

​错误码总览

​通用错误

​资源类错误

​认证

​实体

​文件

​幂等

错误响应格式

错误码总览

通用错误

资源类错误

认证

实体

文件

幂等