跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

当 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。

​
错误码总览

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

​
通用错误

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

​
资源类错误

​
认证

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

​
实体

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

​
文件

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

​
幂等

Create Account · Create SubAccount · Upload A File
幂等中间件会作用在每一个带 body 的 POST 请求上。一旦识别出是重放请求，就会在 handler 执行前短路返回。
codeMessage典型接口What to do
400Idempotency key errorCreate Account · Create SubAccount · Upload A File提供合法的 X-Idempotency-Key —— 2024-08-15 之后创建的实体要求是 RFC-4122 UUID；更早的实体可以是 1–36 位字符串。不要复用超过 24 小时的键。
400Idempotency key auth errorCreate Account · Create SubAccount · Upload A FileX-Idempotency-Key 已缓存在另一个实体名下。每次请求生成新的 UUID，或改用原始调用方的凭证重试。
400Idempotency endpoint errorCreate Account · Create SubAccount · Upload A File同一个 X-Idempotency-Key 之前被用在了另一个接口上。每个接口使用独立的键，或对原接口重新发起请求。
200Request 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 支持。