兼容性 — PassportCraft API

兼容性

我们可以不经通知就在 v1 中变更的内容，以及会需要新主版本的内容。这里以逐条列举代替笼统承诺，好让集成正好针对这一组情况做防御性设计。

路径、方法、作用域、字段名和错误码一律以英文发布，因为接口本身的语言就是英文——这些正是调用方需要照原样输入或比对的内容。每一段代码示例、每一个 JSON 载荷，以及错误响应中携带的那句原文，同样如此：/v1 不读取 Accept-Language，把 API 实际发送的内容翻译出来反而会造成误述。围绕它们的说明文字则跟随本页面的语言。

当前修订版本为 2026-08-01。路径仍为 /v1；修订版本标识的是描述它的那份文档。

我们不会对 v1 做的变更

这些变更需要新的主版本。万一确有需要，现有版本会在迁移期间继续响应。

移除某个操作。
移除或重命名某个参数，或响应中的某个字段。
新增必填参数。
把原本可选的参数改为必填。
更改参数或响应字段的类型。
从枚举中移除某个取值。依据该取值分支的客户端，并没有为它的消失准备分支，于是会以其所用语言处理未覆盖情形的方式失败。
为现有参数新增校验规则。昨天还能成功的请求会开始失败，这实质上是收回了能力，只是披着修复缺陷的外衣。
更改认证或授权要求，包括某个操作所需的作用域。

我们随时可能做的变更

您的集成必须容忍以下全部情况。它们一定会发生，而且不会另行通知。

新增操作。
新增可选参数。
新增可选的请求头。
在响应中新增字段。请以宽容的方式解析响应——只要客户端会拒绝未知字段，我们第一次新增就会让它出问题。
新增响应头。
为枚举新增取值。请把无法识别的取值当作默认分支处理，而不是当作错误。新的护照类别和新的事件类型一定会出现。
把一个错误码细分为更精确的若干个——但仅限于原错误码无法靠重试等运行时逻辑自行化解的情形。如果客户端会依据某个错误码分支，拆分它就属于破坏性变更；如果它只是被记入日志，那就不是。区别在于是否有行为依赖它。

您的客户端必须容忍什么

以下每一条都对应上方我们保留权利做出的一项变更。违反其中任何一条的客户端，都会在我们视为例行的改动上出问题。

对无法识别的响应字段应予忽略，而不是拒绝整个响应。
把无法识别的枚举取值当作默认分支处理，而不是当作错误。
把标识符当作不透明字符串；切勿解析它们，也不要用模式匹配去校验。
不要依赖 JSON 对象中字段的先后顺序，也不要依赖给人看的错误提示的具体措辞。请改为依据机器可读的错误码分支。
遇到 429 时重试；任何其他带 Retry-After 响应头的拒绝也应重试，并按该响应头给出的时间等待。它并非 429 专有：409 resource_busy、503 storage_unavailable 与 503 entitlement_unavailable 同样会带上它，因为在这几种情况下重试正是解决办法。
重试 5xx 时请换用新的 Idempotency-Key。记录下服务端错误的键，会在整个保留期内重放那个错误——这是刻意为之：那次失败可能只是一次已经成功的写入丢了响应，沿用旧键正是为了避免一次失败的写入变成两次。
请留意 Deprecation 与 Sunset 响应头，以及随之而来、关系类型为 successor-version 的 Link 响应头。端点的下线正是由它们预告的，而且会在端点真正停止响应之前很久就出现。

请把每个标识符都当作长度不超过 255 个字符的不透明字符串。不要解析它们，不要校验其格式，也不要假定它们是 UUID——格式可能不经通知就发生变更。

弃用

计划下线的端点会在响应中带上 Deprecation 与 Sunset 请求头，以及指明后继端点的 Link 请求头。它们会在端点真正停止响应之前很久就出现，请留意。