跳转到正文
API 101
本文目录

第 96 篇

编写 API 错误响应文档的最佳实践

要点速览

  • 把错误响应写进 API 契约。 状态码、媒体类型、字段、响应头和重试行为都应和成功响应一样精确。
  • 区分程序判断和人工说明。 客户端应依据稳定的状态码、问题类型或错误码作出判断,不应解析可能变化的消息文本。
  • 告诉开发者如何恢复。 一条有用的错误说明应交代原因、可调整的内容、重试是否安全,以及如何求助。
  • 提供贴近实际的失败示例。 在适用的操作中,展示有代表性的认证、授权、校验、冲突、限流和服务器错误响应。
  • 保护敏感信息。 文档应明确可用的诊断信息,避免在生产响应里泄露堆栈跟踪、密钥、内部主机名或用户隐私数据。

成功请求证明 API 能工作,错误文档决定集成能否应付实际运行中的变化。凭据会过期,输入可能通不过校验,资源可能在读写之间变化,配额可能耗尽,依赖也可能不可用。如果开发者只能靠试错摸清这些情况,每个客户端就会采用不同的恢复策略。

好的错误文档让提供方和调用方对接口行为有一致的预期。它能快速回答五个问题:发生了什么?为什么发生?调用方能修正吗?能安全重试吗?如何追踪这一次失败?

本文假设提供方已经设计好错误语义,重点说明如何记录对外契约。想了解提供方如何设计状态码、响应体和网关行为,请先读 API 错误处理:状态码、错误响应和最佳实践。需要客户端实现模式,可以参考调用 API 时如何处理错误。

从 HTTP 语义出发

HTTP API 应按标准语义选用状态码。RFC 9110定义了核心类别和状态码。即使通用客户端、缓存、代理、可观测性工具和网关无法理解响应体,也能根据状态码采取行动。

文档应明确区分常见情况:

状态码典型含义调用方该怎么做
400 Bad Request语法错误或请求总体无效先修正请求,再尝试
401 Unauthorized缺少认证凭据,或凭据无效、已过期获取有效凭据,再按操作的重试约定尝试
403 Forbidden已认证的调用方缺少权限申请权限或更换操作
404 Not Found调用方无法获取目标资源检查标识符,避免盲目重试
409 Conflict请求与资源当前状态冲突刷新状态,或按具体冲突类型的说明处理
422 Unprocessable Content语法有效,但一个或多个值不符合语义规则修正指出的字段
429 Too Many Requests请求被速率或配额策略拒绝遵守 Retry-After 或文档规定的重置提示
500 Internal Server Error提供方发生意外故障按策略判断能否重试,并报告追踪 ID
502 Bad Gateway中间服务收到无效的上游响应按瞬时故障策略有限重试
503 Service Unavailable服务暂时无法处理请求遵守 Retry-After,并采用带抖动的退避

不要返回 200 OK,却把错误藏在响应体里。通用工具无法正确识别这种失败,监控面板也会把它算作成功。多个操作如果用同一状态码表示不同的业务条件,应提供机器可读的领域标识加以区分。

1flowchart TD
2    E["Request failed"] --> A{"Authenticated?"}
3    A -- "No" --> S401["401: obtain valid credentials"]
4    A -- "Yes" --> P{"Authorized?"}
5    P -- "No" --> S403["403: request access or change action"]
6    P -- "Yes" --> V{"Request valid?"}
7    V -- "No" --> S400["400 or 422: correct request"]
8    V -- "Yes" --> C{"State conflict?"}
9    C -- "Yes" --> S409["409: refresh or resolve conflict"]
10    C -- "No" --> T{"Rate or service transient?"}
11    T -- "Yes" --> S429["429 or 503: bounded retry"]
12    T -- "No" --> S500["5xx: trace and escalate"]
13
14    classDef action fill:#f6ffed,stroke:#389e0d,color:#173b0b;
15    classDef question fill:#fff7e6,stroke:#d48806,color:#5c3b00;
16    class A,P,V,C,T question;
17    class S401,S403,S400,S409,S429,S500 action;

可以按认证、授权、校验、状态冲突和暂时性故障分辨恢复路径。只有在操作允许重试时,才按约定等待并有限重试。对于其他服务端故障,先保留追踪信息,再按支持流程处理。

统一错误响应结构

RFC 9457为 HTTP API 定义了 Problem Details。它的 JSON 媒体类型是 application/problem+json,标准成员包括:

  • type:标识问题类别的 URI;
  • title:面向人的问题类别简述;
  • status:重述 HTTP 状态码,方便阅读;
  • detail:面向人的、针对本次问题的说明;
  • instance:标识本次问题的 URI 引用。

如果客户端需要结构化的领域信息,API 可以增加扩展成员。下面是一份校验失败响应示例:

1HTTP/1.1 422 Unprocessable Content
2Content-Type: application/problem+json
3Content-Language: en
4X-Request-ID: req_01J1K9Y7A6E5Q4P3
5
6{
7  "type": "https://developer.example.com/problems/validation-error",
8  "title": "The request contains invalid values.",
9  "status": 422,
10  "detail": "Correct the listed fields and submit the request again.",
11  "instance": "/problems/req_01J1K9Y7A6E5Q4P3",
12  "errors": [
13    {
14      "code": "minimum",
15      "pointer": "/items/0/quantity",
16      "detail": "Value must be greater than or equal to 1."
17    }
18  ]
19}

顶层字段标识主要问题。errors 是此问题类型的扩展,为同类校验失败提供字段级细节。文档应说明扩展的 Schema、指针格式、最多返回多少项,以及顺序是否稳定。

Problem Details 是一种常见选择,并非所有 API 风格都必须采用。成熟的 API 可以保留另一种统一结构,避免破坏现有客户端。GraphQL 通常在响应模型中返回 errors 数组,异步协议也可能使用自己的错误帧。无论选择哪种格式,都应保持同样的设计原则:稳定的机器标识、清楚的人工说明、有据可查的恢复步骤,以及可追踪性。

保持标识稳定

面向人的消息会因表达优化或本地化而变化,客户端代码不能解析这些文字。请明确记录调用方判断时应使用的确切值,通常是 type、领域错误码 code,或者两者。

好的标识描述的是错误条件,而非内部实现:

1https://developer.example.com/problems/insufficient-balance
2inventory_unavailable
3idempotency_conflict

避免使用 database_error_42 这类暴露内部实现、也难以在架构变更后保持稳定的标识。如果问题 type 使用 HTTPS URL,请使用自己控制的域名,并让该 URL 指向长期可用的问题说明。

建立便于查找的错误目录

每个操作页面应列出与该操作有关的错误,统一目录则详细定义可复用的问题类型。调用方既需要快速找到相关错误,也需要看懂它的完整含义。

每种错误类型应记录:

  1. 机器标识:确切的 type URI 或错误码。
  2. HTTP 状态码和媒体类型:包括相关的响应头。
  3. 触发条件:什么情况下会发生此错误。
  4. 调用方操作:如何预防、修正、重试或寻求支持。
  5. 重试策略:能否安全重试、适用条件和等待时间。
  6. 示例:有代表性的请求场景和完整响应。
  7. 安全说明:例如 404 是否有意隐藏资源是否存在。
  8. 生命周期:该类型何时引入或变更。

使用容易搜索的标题和名称。“insufficient-balance:充值或选择其他账户”比“支付错误”更容易找到。可以从操作的 409 响应直接链接到目录条目。

精确记录重试行为

“稍后再试”不能代替重试策略。要说明操作是否幂等、调用方是否需要幂等键、哪些响应头决定等待时间,以及客户端允许重试几次或多长时间。

对 429 和 503,如果服务发送 Retry-After,文档就应说明该字段。对于其他瞬时故障,可在允许重试的前提下推荐带抖动的指数退避,并限制尝试次数或总耗时。校验、授权或冲突错误在相应条件改变前不应重试。

如果某个 POST 操作可以凭幂等键安全重试,就要记录键的作用域、保留期、格式和冲突行为。前一次写入的结果不明时,先确认其结果;如果契约允许重试,应在保留期内沿用同一个键和原请求体。只有明确发起另一项独立的逻辑操作时,才使用新键。

在 OpenAPI 中描述错误

OpenAPI 应覆盖调用方预期处理的每种响应,不能只列 200 和通用的 default。可以复用基础问题 Schema,同时保留操作特有的描述与示例:

1paths:
2  /orders:
3    post:
4      operationId: createOrder
5      responses:
6        '201':
7          description: Order created.
8        '409':
9          description: The idempotency key conflicts with an earlier request.
10          content:
11            application/problem+json:
12              schema:
13                $ref: '#/components/schemas/Problem'
14              examples:
15                idempotencyConflict:
16                  value:
17                    type: https://developer.example.com/problems/idempotency-conflict
18                    title: The idempotency key was already used.
19                    status: 409
20                    detail: Check the previous result before retrying. Reuse the same key with the original request body within the retention window. Use a new key only for a different logical operation.
21                    instance: /problems/req_01J1K9Y7A6E5Q4P3
22        '429':
23          description: The client exceeded its request rate.
24          headers:
25            Retry-After:
26              description: Seconds to wait before another request.
27              schema:
28                type: integer
29                minimum: 1
30          content:
31            application/problem+json:
32              schema:
33                $ref: '#/components/schemas/Problem'
34components:
35  schemas:
36    Problem:
37      type: object
38      required: [type, title, status]
39      properties:
40        type:
41          type: string
42          format: uri-reference
43        title:
44          type: string
45        status:
46          type: integer
47          minimum: 400
48          maximum: 599
49        detail:
50          type: string
51        instance:
52          type: string
53          format: uri-reference

校验示例是否符合 Schema,并用契约测试覆盖真实失败。只测成功路径,就无法发现生产代理实际返回的是 HTML,而契约写的是 JSON。

验证每个错误来源

错误可能来自面向调用方的网关、身份提供方、服务代码、下游服务或基础设施。契约应以调用方在公开边界收到的响应为准。

1sequenceDiagram
2    participant C as Client
3    participant G as API Gateway
4    participant S as Service
5    participant D as Dependency
6
7    C->>G: Request
8    alt Authentication or rate policy fails
9        G-->>C: Standard public problem response
10    else Request reaches service
11        G->>S: Forward request with trace context
12        alt Domain validation fails
13            S-->>G: Domain problem
14            G-->>C: Preserve documented status and type
15        else Dependency fails
16            S->>D: Call dependency
17            D-->>S: Timeout or internal failure
18            S-->>G: Sanitized service problem
19            G-->>C: Stable public problem plus request ID
20        end
21    end

认证或限流失败时,网关可直接返回公开错误响应,请求不必到达上游。如果请求已转发,领域校验错误应保留契约规定的状态码和问题类型。依赖超时或故障则应先去除敏感细节,再返回稳定的公开响应和请求 ID。

Apache APISIX 等 API 网关可以在调用上游前执行认证、限流和路由。文档应同时记录网关产生的响应和应用产生的响应。网关如果统一错误格式,应保留正确的 HTTP 语义和有用的追踪标识,避免把所有错误都改成无法区分的 500。

为缺少凭据、权限范围不足、JSON 格式错误、关键校验规则、资源不存在、修订版本过期、幂等键重复、限流、超时及主动注入的服务故障编写失败测试。断言状态码、内容类型、稳定标识、必需响应头和 Schema,同时确认响应中没有敏感字段。

写出安全且有用的错误消息

错误详情应帮助调用方修正请求,而不是调试提供方的实现。不要返回堆栈跟踪、SQL 片段、内部主机名、文件系统路径、访问令牌、会话 ID 或其他客户的数据。RFC 9457 提醒,Problem Details 可能暴露攻击线索和实现细节。

“出了点问题”同样不够。一条安全的响应可以指出出错字段、预期约束、公开请求 ID 和支持渠道,同时避免暴露内部状态。

谨慎处理 instance 和追踪标识。如果某次错误的 URL 可打开诊断详情,就应进行授权检查,防止跨租户访问。文档还应说明用户是否需要把请求 ID 提供给支持团队,以及这个 ID 多久之内可以查到。

本地化可以改变面向人的 title 和 detail,机器标识应保持稳定。如果响应根据 Accept-Language 选择语言,应记录回退语言,并发送 Content-Language。客户端仍应使用稳定的结构化字段作出判断。

错误文档审阅清单

  • 公开边界的 HTTP 状态码是否符合标准语义?
  • 每种预期失败是否都有稳定的机器标识?
  • 人工消息的修改或翻译是否不会影响客户端?
  • 每条错误是否说明如何修正、重试和求助?
  • 是否记录了 Retry-After、限流、认证和追踪相关的响应头?
  • 操作页面是否链接到相关的错误目录条目?
  • OpenAPI Schema 和示例是否符合各层实际返回的响应?
  • 批量错误和字段级错误是否限制了返回数量,并明确规定了结构?
  • 是否排除了密钥、个人数据和内部实现细节?
  • 是否像对待其他契约变更一样,检测并告知错误响应的破坏性变更?

小结

错误响应是生产客户端需要谨慎处理的一部分契约。准确选用 HTTP 状态码,提供稳定的问题标识,为每种失败配上恢复建议,并在调用方实际访问的边界验证文档。

接下来,可以读如何在 API 文档中提供代码示例,把成功和失败场景都写成开发者能安全复制、理解和维护的代码。

编辑本篇文章

获取方案