跳转到内容

ecentic API 错误。

ecentic API 上的每一次失败都会返回类型化的 problem 文档,而不是 HTML 页面。代码即契约:稳定、可机器读取,并且可以安全地用于分支处理。

RFC 9457 · 稳定代码 · 解决建议

01

problem 的结构

API 返回的每个 4xx 和 5xx 都使用同一种媒体类型和同一种 schema。

application/problem+json

响应会携带 Content-Type: application/problem+json——有意不使用 application/json,因为通用客户端需要通过媒体类型判断响应体描述的是错误,而不是请求的资源。

响应示例

响应解析

type
用于标识问题的 URI,并锚定到本参考文档。
code
客户端可据此进行分支处理的稳定标识符。
title
简短的人类可读摘要。
status
HTTP 状态码,并在响应体中重复返回。
detail
本次请求具体出现的问题。
resolution
解决失败问题的下一步操作。
documentation
此响应对应的参考页面。
instance
生成该响应的请求路径(如已知)。
02

错误目录

代码一经发布即被冻结。标题和提示可以调整措辞;代码不可以。

12已发布的问题代码

打开任意代码即可查看其解决方法。每个代码都有永久链接。

永久链接到 not-found

解决方法

Check the path against the OpenAPI document at /openapi.json or the API catalog at /.well-known/api-catalog.

永久链接到 method-not-allowed

永久链接到 unauthenticated

永久链接到 unauthorized

永久链接到 payment-required

永久链接到 subscription-required

永久链接到 invalid-request

永久链接到 validation-failed

永久链接到 conflict

永久链接到 rate-limited

永久链接到 upstream-timeout

永久链接到 internal-error