# 速率限制

> 按密钥计算的请求额度、描述它的那唯一一个响应头，以及怎样稳稳地待在额度以内。

Source: https://developers.backresto.com/zh/docs/rate-limits

合作方 API 允许**每把密钥每分钟 300 个请求**。窗口是滚动的一分钟，而额度属于密钥，
不属于餐厅、也不属于你的公司，所以两个部署用两把密钥，就有两份额度。
[MCP 端点](https://developers.backresto.com/zh/docs/mcp)用的是同一份额度：一次工具调用就是一个请求。

超出之后会返回 `429`，附带一份 type 为 `rate-limit-exceeded` 的 problem 文档，以及
一个 `Retry-After` 响应头，给出额度重新充满还需要多少秒。等它过去；不要提前重试，
因为一个来得太早的请求会耗掉额度却不会成功。

`Retry-After` 是关于额度的唯一一个响应头。没有 `X-RateLimit-Remaining` 可以盯着，
所以请按设计来给你的客户端定速，而不是靠读一个计数器。下面这些习惯就是那个设计。

## 怎样轻松待在额度以内

三个习惯几乎覆盖了所有集成：

**整页整页地取。** `limit=100` 走完同一个集合，用的请求数只有 `limit=25` 所需的
四分之一。一个请求的成本是这个请求本身，不是它返回的行数。

**只在需要文件的时候才去取。** 一张照片的记录已经在 `data.asset` 里说明了那个文件
是什么：类型、大小和摘要。只为你正要展示或存储的照片调用 assets 端点，而不是为一
次遍历中的每一条记录都去调，并跳过那些 `sha256` 你已经持有的。

**回填要串行做。** 用十个并行的工作进程去走一年的历史，是唯一一种能可靠撞上限制的
做法。一个工作进程用 `limit=100`，几分钟就能走完一家繁忙餐厅的一整年。

## 如果你确实需要更多

告诉我们工作负载是什么。这个限制的存在，是为了不让一个行为失常的客户端拖累服务、
连累那家数据属于它的餐厅，而不是为了限量供应；一个讲清楚了的、正当的工作负载是
一场对话，不是一次拒绝。

## 其他值得知道的限制

| 限制 | 数值 |
| --- | --- |
| 每把密钥的请求数 | 每分钟 300 个 |
| 每页大小 | 100 条记录 |
| 照片和文件的签名 URL 有效期 | 15 分钟 |
| 每个账号的有效密钥数 | 10 |

这些是由 API 强制执行的，而不只是被它描述出来：超出前两项中的任何一项，得到的是
`429` 或 `400`，而不是悄悄被截断。