错误与状态码
本页汇总了贷款领域 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" }
]
}| 字段 | 类型 | 说明 |
|---|---|---|
error | string | 简短的、便于阅读的摘要。 |
fieldErrors[].path | string | 指向出错字段的点分路径。(root) 表示请求体本身,例如 JSON 解析失败时。 |
fieldErrors[].message | string | 便于阅读的说明。 |
部分路由在查询参数失败时返回 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" }
]
}| 字段 | 类型 | 说明 |
|---|---|---|
error | string | 便于阅读的摘要。 |
code | string | 稳定的机器可读代码;参见术语表。 |
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_CONFLICT | 409 | POST /borrowers、POST /loans、POST /payments。 | 已存在具有相同 id 的有效行。 |
PORTFOLIO_NOT_FOUND | 404 | 所有单条记录写入路由。 | 请求体中的 portfolioId 在您的组织中不存在。 |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans、POST /payments。 | borrowerId 或 loanId 引用的行在同一投资组合中不作为有效行存在。 |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status。 | 变更前后的状态组合不在变更矩阵中。 |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status。 | 该 Idempotency-Key 已用于另一次状态变更。请使用新密钥发送新的状态变更。 |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports。 | 该 Idempotency-Key 已用于请求参数(kind、filename、sizeBytes 等)不同的另一次导入。响应包含 importId 和 mismatchedFields。请使用新密钥发送新的导入。 |
MONITORING_INVESTOR_FORBIDDEN | 403 | 所有监控贷款路由,包括批量 NDJSON。 | 调用方是投资者账户;投资者不能使用监控数据 API。 |
CHECK_VIOLATION | 400 | POST /payments。 | 某条数据规则未通过(通常是豁免不变量;schema 层会在校验时先拒绝相同的结构)。 |
NOT_FOUND | 404 | GET /borrowers/{id}、GET /payments/{id}、PATCH /loans/.../status、POST /payments/{id}/cancel、GET /loans/{externalId}。 | 所查找的行在给定范围内不作为有效行存在,或属于其他组织。 |
UNKNOWN_KIND | 400 | POST /imports。 | kind 不是六种贷款类型之一。响应中包含一个 allowed 数组。 |
COMMIT_FAILED | 409 | POST /imports/{id}/commit。 | 平台找不到上传的文件;通常是上传从未完成。请重试上传,然后重新提交。 |
批量 NDJSON 代码空间
| 代码 | 状态 | 触发条件 |
|---|---|---|
batch_too_large | 413 | 请求体超过 10 000 行或 10 MB。通过 error 和 fieldErrors[].message 区分是行数上限还是字节上限。 |
portfolio_id_required | 400 | ?portfolioId=<UUID> 缺失或不是有效的 UUID。 |
portfolio_not_found | 404 | ?portfolioId= 在您的组织中不作为有效投资组合存在。 |
invalid_body | 400 | 无法将请求体读取为文本。 |
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 响应——只要请求本身格式正确,整个批次就算成功;逐行代码告诉您哪些数据已落库。
重试语义
适用于任何变更类路由的安全重试模式如下:
- 为每个逻辑操作生成确定性的
Idempotency-Key。UUIDv4 加上路由区分标识即可。 - 携带该键发送请求。
- 遇到
2xx、409 ID_CONFLICT、409 IDEMPOTENCY_CONFLICT、409 IDEMPOTENCY_KEY_REUSED、404、403、400、413或422中的任何一种——不要重试。结果已是最终结果。 - 遇到
429——在Retry-After响应头指定的时长后重试。 - 遇到
500或网络错误——以指数退避方式重试少量固定次数。无论第一次尝试是否送达,Idempotency-Key都能确保重试安全。
使用相同 Idempotency-Key 重试一个已成功的请求时,会返回与原始请求相同的响应,且相关实体上带有 reused: true。这是从网络抖动中恢复的标准正常路径。
平台从不返回的内容
为便于运维排查,了解“反面清单”很有用:
- 平台不会把任何
5xx状态码当作功能特性。500永远是需要修复的缺陷;切勿编写依赖特定500结构的客户端逻辑。 - 任何
404响应都不会泄露租户信息。 对存在于其他组织中的行返回的404,与对任何地方都不存在的行返回的404看起来完全相同。不要编写推断跨租户存在性的客户端逻辑。 - 任何成功响应都不会携带名为
success: false的请求体字段。 状态码是判断调用是否成功的权威依据;请求体结构承载详细信息。 - 任何写入路由都不会以路径参数的方式(“Location”响应头)返回其 UUID。 创建的 UUID 出现在响应体的
id字段中。