Waafir
本页面为机器翻译,尚待人工审核,可能存在错误。

错误与状态码

本页汇总了贷款领域 API 所有路由使用的响应封装。各路由的文档列出了该路由会返回的状态码;本页则记录每种响应封装的结构,以及您可能收到的命名 code 值目录。

请在集成前通读一遍;每当遇到意料之外的非 2xx 状态时,再回来查阅。

状态码目录

状态出现场景示例路由
200 OK读取成功、幂等重放、软取消、批量批次已处理、状态变更。所有非创建类路由。
201 Created单条记录路由上首次创建成功。POST /borrowers。
202 Accepted异步导入已启动——工作在后台继续进行。POST /imports。
204 No Content目前没有任何贷款领域路由返回此状态。—
400 Bad Request请求校验失败:JSON 格式错误、查询格式错误、违反 schema。所有变更类路由。
401 Unauthorized缺少 Authorization 请求头、令牌未知或令牌已吊销。所有路由。
403 Forbidden调用方是投资者账户;投资者不能使用监控数据 API(MONITORING_INVESTOR_FORBIDDEN)。非管理员使用 ?unmask=true 不会返回 403,而是返回 PII 已掩码的 200。所有路由。
404 Not Found资源不存在或属于其他组织。所有引用资源的路由。
409 Conflict已存在具有此 id 的有效行,或 Idempotency-Key 被重复用于不同的状态变更,或提交阶段看不到已上传的文件。POST /borrowers、PATCH /loans/.../status、POST /imports/{id}/commit。
413 Payload Too Large批量 NDJSON 批次超过行数或字节上限。POST /bulk/{entity}。
422 Unprocessable Entity被引用的行在同一投资组合中不作为有效行存在(REFERENCED_ENTITY_NOT_FOUND),或请求的状态变更不在变更矩阵中(INVALID_STATUS_TRANSITION)。校验失败使用 400。POST /loans、POST /payments、PATCH /loans/{loanRef}/status。
429 Too Many Requests超出速率限制。平台按组织实施速率限制;响应头 Retry-After 指明需等待的秒数。所有路由。
500 Internal Server Error未处理的平台错误。请视为暂时性错误;使用相同的 Idempotency-Key 重试是安全的。所有路由。

将 429 以外的任何 4xx 视为请求缺陷——您的客户端逻辑应拒绝该输入,而不是重试。将 429 和 500 视为暂时性错误,并以退避方式重试;Idempotency-Key 可确保重试安全。

标准响应封装

贷款领域 API 对非成功状态码使用三种响应封装。响应封装的结构会告诉您所面对的是哪类失败。

校验响应封装——400 Bad Request

用于违反 schema、查询参数格式错误和路径格式错误。

{
  "error": "Validation failed",
  "fieldErrors": [
    { "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
    { "path": "termMonths", "message": "termMonths must be > 0" }
  ]
}
字段类型说明
errorstring简短的、便于阅读的摘要。
fieldErrors[].pathstring指向出错字段的点分路径。(root) 表示请求体本身,例如 JSON 解析失败时。
fieldErrors[].messagestring便于阅读的说明。

部分路由在查询参数失败时返回 errors[] 而不是 fieldErrors[](框架约定因接口而异)。两者的 path/message 结构完全相同;解析时可将这两个数组名视为可互换。

命名代码响应封装——4xx

当失败有平台以稳定的 code 值命名的具体原因时使用。fieldErrors 是否出现是可选的,取决于该失败能否归因于某个具体字段。

{
  "error": "a borrower with this id already exists",
  "code": "ID_CONFLICT",
  "fieldErrors": [
    { "path": "id", "message": "a borrower with this id already exists" }
  ]
}
字段类型说明
errorstring便于阅读的摘要。
codestring稳定的机器可读代码;参见术语表。
fieldErrors[]array | absent当失败指向具体字段时出现。

部分响应封装携带额外的结构化上下文——例如 batch_too_large 包含一个 fieldErrors 块,指明超出的是哪个上限。各路由的文档会列出这些情况。

简单错误响应封装——404 / 401

用于简洁的响应,此时附加上下文对调用方没有帮助。404 是典型例子:

{ "error": "Not found" }

部分路由返回 { "error": "...", "code": "NOT_FOUND" };对于 404,请将 code 是否存在视为参考信息,不要依赖它。

两套代码空间:大写与小写

贷款领域 API 使用两个不同的 code 命名空间,按接入方式有意区分:

  • 单条记录路由(POST、PATCH、取消以及对账 GET)返回 UPPER_CASE 代码值:ID_CONFLICT、PORTFOLIO_NOT_FOUND、REFERENCED_ENTITY_NOT_FOUND、INVALID_STATUS_TRANSITION、CHECK_VIOLATION、NOT_FOUND、UNKNOWN_KIND、COMMIT_FAILED、IDEMPOTENCY_CONFLICT、IDEMPOTENCY_KEY_REUSED、MONITORING_INVESTOR_FORBIDDEN。批量 NDJSON 路由也会以大写形式返回 MONITORING_INVESTOR_FORBIDDEN。
  • 批量 NDJSON 路由返回 lower_case 代码值:batch_too_large、portfolio_not_found、portfolio_id_required、invalid_body、invalid_json,以及下文记录的逐行代码。

在客户端中按 code 分支时,请精确匹配大小写。两套代码空间各自保持稳定;不要对它们做大小写规范化。

错误码术语表

平台为每一种命名的失败情形附加一个稳定的 code。请使用这些代码进行程序化分支;error 消息文本可能会变化。

单条记录代码空间

代码状态返回者触发条件
ID_CONFLICT409POST /borrowers、POST /loans、POST /payments。已存在具有相同 id 的有效行。
PORTFOLIO_NOT_FOUND404所有单条记录写入路由。请求体中的 portfolioId 在您的组织中不存在。
REFERENCED_ENTITY_NOT_FOUND422POST /loans、POST /payments。borrowerId 或 loanId 引用的行在同一投资组合中不作为有效行存在。
INVALID_STATUS_TRANSITION422PATCH /loans/{loanRef}/status。变更前后的状态组合不在变更矩阵中。
IDEMPOTENCY_CONFLICT409PATCH /loans/{loanRef}/status。该 Idempotency-Key 已用于另一次状态变更。请使用新密钥发送新的状态变更。
IDEMPOTENCY_KEY_REUSED409POST /imports。该 Idempotency-Key 已用于请求参数(kind、filename、sizeBytes 等)不同的另一次导入。响应包含 importId 和 mismatchedFields。请使用新密钥发送新的导入。
MONITORING_INVESTOR_FORBIDDEN403所有监控贷款路由,包括批量 NDJSON。调用方是投资者账户;投资者不能使用监控数据 API。
CHECK_VIOLATION400POST /payments。某条数据规则未通过(通常是豁免不变量;schema 层会在校验时先拒绝相同的结构)。
NOT_FOUND404GET /borrowers/{id}、GET /payments/{id}、PATCH /loans/.../status、POST /payments/{id}/cancel、GET /loans/{externalId}。所查找的行在给定范围内不作为有效行存在,或属于其他组织。
UNKNOWN_KIND400POST /imports。kind 不是六种贷款类型之一。响应中包含一个 allowed 数组。
COMMIT_FAILED409POST /imports/{id}/commit。平台找不到上传的文件;通常是上传从未完成。请重试上传,然后重新提交。

批量 NDJSON 代码空间

代码状态触发条件
batch_too_large413请求体超过 10 000 行或 10 MB。通过 error 和 fieldErrors[].message 区分是行数上限还是字节上限。
portfolio_id_required400?portfolioId=<UUID> 缺失或不是有效的 UUID。
portfolio_not_found404?portfolioId= 在您的组织中不作为有效投资组合存在。
invalid_body400无法将请求体读取为文本。
invalid_json(逐行)某行不是有效 JSON。出现在逐行 errors[] 数组中;批次返回 200。

不在本术语表中的代码,表示平台在本页上次修订后新增了命名代码。请始终将 code 值与应用程序的错误一起原样记录,以便工程团队进行关联排查。

逐行错误码(批量与异步导入)

批量 NDJSON 和异步导入都会返回逐行错误。批量接口使用一组值;异步导入接口使用一组相似但略有不同的值(尤其是它使用 validation_error 而不是 validation_failed,这反映出它是较早的接口)。逐行条目描述的是成功批次内单个行的失败,而不是响应封装层面的失败。

批量 NDJSON 逐行代码

逐行代码触发条件
validation_failed该行未通过 schema 校验。message 字段包含校验错误。
fk_violation该行中的外键引用(例如 borrowerId、loanId)未能解析为同一投资组合中的有效行。
unique_violation已存在具有相同 (portfolio, externalId) 或 id 的有效行。(没有单独的 id_conflict 逐行代码;两种调用方 ID 冲突都在此报告。)
check_violation某条数据规则未通过——通常是还款上的豁免规则。
db_error存储该行时发生意外错误。该行被报告为失败;批次继续处理。
invalid_json该行不是有效 JSON。平台会继续处理批次的其余部分。

异步导入逐行代码

逐行代码触发条件
parse_error该行不是有效 JSON。
validation_error该行未通过 schema 校验。
portfolio_mismatch该行的 portfolioId 与导入的锚点投资组合不一致。
processor_error处理该行时处理程序意外失败。

存储某行时发生的错误(引用缺失、重复、数据规则未通过)会归入上述某个代码,详情见 errorMessage。

逐行错误永远不会上升为批量接口的顶层非 200 响应——只要请求本身格式正确,整个批次就算成功;逐行代码告诉您哪些数据已落库。

重试语义

适用于任何变更类路由的安全重试模式如下:

  1. 为每个逻辑操作生成确定性的 Idempotency-Key。UUIDv4 加上路由区分标识即可。
  2. 携带该键发送请求。
  3. 遇到 2xx、409 ID_CONFLICT、409 IDEMPOTENCY_CONFLICT、409 IDEMPOTENCY_KEY_REUSED、404、403、400、413 或 422 中的任何一种——不要重试。结果已是最终结果。
  4. 遇到 429——在 Retry-After 响应头指定的时长后重试。
  5. 遇到 500 或网络错误——以指数退避方式重试少量固定次数。无论第一次尝试是否送达,Idempotency-Key 都能确保重试安全。

使用相同 Idempotency-Key 重试一个已成功的请求时,会返回与原始请求相同的响应,且相关实体上带有 reused: true。这是从网络抖动中恢复的标准正常路径。

平台从不返回的内容

为便于运维排查,了解“反面清单”很有用:

  • 平台不会把任何 5xx 状态码当作功能特性。 500 永远是需要修复的缺陷;切勿编写依赖特定 500 结构的客户端逻辑。
  • 任何 404 响应都不会泄露租户信息。 对存在于其他组织中的行返回的 404,与对任何地方都不存在的行返回的 404 看起来完全相同。不要编写推断跨租户存在性的客户端逻辑。
  • 任何成功响应都不会携带名为 success: false 的请求体字段。 状态码是判断调用是否成功的权威依据;请求体结构承载详细信息。
  • 任何写入路由都不会以路径参数的方式(“Location”响应头)返回其 UUID。 创建的 UUID 出现在响应体的 id 字段中。