# 速率限制

> 每个套餐设定每分钟请求数：20、40 或 120，按滑动 60 秒窗口统计。每个响应带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。超限返回 HTTP 429，缓存响应也计数。

## 各套餐的限制

| 每分钟请求数 | 满速率下每天的请求数 |
| ------ | ---------- |
| 20     | 28,800     |
| 40     | 57,600     |
| 120    | 172,800    |

所有套餐包含相同的接口和数据。套餐名称和价格见[定价](https://amodb.dev/zh/pricing/)。

## 窗口如何运作

amodb 统计每个密钥在过去 60 秒内的请求。窗口是滑动的：12:00:30 发出的请求在 12:01:30 停止计数。不会在整分钟重置，所以稳定的速率比突发请求更合适。

密钥检查和速率限制先于边缘缓存执行。从缓存返回的响应仍然算作一个请求。

## 响应头

每次带密钥的调用都会返回这些响应头：

| 响应头                     | 含义                       |
| ----------------------- | ------------------------ |
| `X-RateLimit-Limit`     | 此密钥每 60 秒允许的请求数。         |
| `X-RateLimit-Remaining` | 当前窗口中剩余的请求数。             |
| `X-RateLimit-Reset`     | 距离最早被计入的请求离开窗口还有多少秒。     |
| `Retry-After`           | 仅在 429 时返回：下一次调用前要等待的秒数。 |

## 达到限制时

响应是 HTTP 429，响应体为 TMDB 的错误格式：

```json
{
  "success": false,
  "status_code": 25,
  "status_message": "Your request count (41) is over the allowed limit of (40)."
}
```

等待 `Retry-After` 秒，然后重试。不要在紧凑的循环里重试。

```js
async function amodb(path) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(`https://api.amodb.dev${path}`, {
      headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
    });
    if (res.status !== 429) return res.json();
    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("amodb: still rate limited after 3 attempts");
}
```

```python
import os
import time
import requests

def amodb(path):
    for _ in range(3):
        res = requests.get(
            f"https://api.amodb.dev{path}",
            headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
            timeout=10,
        )
        if res.status_code != 429:
            return res.json()
        time.sleep(int(res.headers.get("Retry-After", "1")))
    raise RuntimeError("amodb: still rate limited after 3 attempts")
```

## 保持在限制之内

- 在你这一侧缓存响应。详情很少变化，6 小时是安全的默认值。
- 用 `append_to_response` 在一个请求中取得详情、演职员和图片，而不是发三个请求。
- 分散批处理任务：每分钟 40 个请求时，每 1.5 秒发一个请求。
- 读取 `X-RateLimit-Remaining`，在它降到 0 之前放慢速度。

## 常见问题

### 我的所有密钥共用一个限制吗？

每个密钥在自己的窗口中单独计数，每个密钥都获得你套餐的速率。每个应用使用一个密钥，这样繁忙的应用不会拖慢另一个应用。

### 有每日上限吗？

没有。唯一的限制是每分钟速率。每分钟 40 个请求时，一个密钥每天最多可发出 57,600 个请求。

### 图片请求计数吗？

不计数。img.amodb.dev 上的图片无需密钥，也不计入你的速率。

## 相关页面

- [定价](https://amodb.dev/zh/pricing/): amodb 套餐的区别只在每分钟请求数：20、40 或 120。所有套餐都包含全部兼容 TMDB v3 和 OMDb 的数据。预付，不续费，无试用。
- [错误](https://amodb.dev/zh/errors/): amodb 的每个错误及其 HTTP 状态、TMDB status_code 和消息，以及 OMDb 错误结构。每个错误的含义和客户端下一步该做什么。
- [认证](https://amodb.dev/zh/authentication/): 如何发送 amodb 密钥：查询中的 api_key、Bearer 请求头，或 OMDb 的 apikey。含密钥格式、保管和 401 错误。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-18. Source: https://amodb.dev/zh/rate-limits/