Definition
API 的速率限制如何适用？
限额按组织和端点类别分别适用，并在每次响应中通过响应头告知限额、剩余额度与重置时间。公开的护照解析与贵方配额分开计量，因为一次扫描高峰不应吃掉签发流水线的预算。
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
类别
并非所有端点都按同一标准计量
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
请求头
每个响应都会告诉您什么
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));客户端设计
一个规矩的客户端会做什么
读取响应头
随当前配额自动调整，而非假定某个文档中记载的数值。
带抖动地退避重试
随机延迟，避免并行工作进程同步重试。
使用批量路径
存量数据回补走批量接口，而不是对单资源端点做循环调用。
把两条流水线分开
签发与报表使用不同的密钥，因此一方不会把另一方的配额耗尽。
限制重试次数
放弃并把失败暴露出来，而不是无限重试。
触顶前预警
对剩余配额发出预警，这样第一个信号就不会是生产环境中的 429。
答疑
常见问题
实际的限额是多少？
这取决于您的套餐以及端点类别，并载于您的合同之中，而非本页。公开的数字在一个版本之内就会过时，依此估算规模的集成方会在生产环境中撞上真实上限。请改读响应头——它们始终是最新的。
客户端遇到 429 应如何应对？
若存在 `Retry-After`，请遵循它；否则采用带抖动的指数退避，并限制重试次数。立即重试，或让大量工作进程按固定间隔重试，会把一次短暂的限流变成持续的限流 —— 正是那种把小问题拖成故障的惊群效应。
公开的护照解析也受同样的限流吗？
不是。解析是公开、可缓存且本就呈突发态势的，因此它由缓存与边缘容量来治理，而不是由贵方配额。某件产品意外走红，不应消耗签发流水线赖以运转的配额，这正是两条路径分开计量的原因。
大量历史目录数据应如何加载？
走批量导入路径，而不是循环调用单资源端点。批量接口面向吞吐设计，以异步作业运行并由您轮询；单资源端点则面向时延设计。用错接口是自招限流最常见的原因。
限额是按密钥还是按组织计算？
按组织计量，并按密钥分别可见。当您按服务划分密钥时这一点很重要：一个行为异常的服务可能耗尽共享额度，而按密钥的明细能让您迅速定位，而不必逐个排除。