# 速率限制与 HTTP 头

> 每个 API 密钥的请求速率限制、速率限制响应头、429 和 503 响应中的 retry-after，以及 Fileverity API 设置的其他响应头。

来源： https://fileverity.com/zh/docs/rate-limits

每个 API 密钥每分钟最多可发起 120 次请求。该限制按一分钟的时间窗口计数，适用于所有接口，包括返回错误的请求。窗口用尽后，后续请求将收到 `429`，错误码为 `rate_limited`，直到窗口重置。

需要更高的限额或批量价格？[联系销售团队](https://fileverity.com/zh/contact)。

## 速率限制响应头

对已通过身份验证的请求，每个响应都会携带您当前时间窗口的状态：

| 请求头 | 含义 |
| --- | --- |
| `x-ratelimit-limit-requests` | 每个窗口允许的请求数。 |
| `x-ratelimit-remaining-requests` | 当前窗口剩余的请求数。 |
| `x-ratelimit-reset-requests` | 距窗口重置的秒数。 |
| `retry-after` | 仅在错误码为 `rate_limited` 的 `429` 响应和错误码为 `service_unavailable` 的 `503` 响应中出现。表示发起下一次请求前需等待的秒数。`pending_files_limit`（同为 `429`）不带此响应头。 |

因缺少密钥或密钥无效而被拒绝的请求（`401`）不带这些响应头。

**遵循 retry-after: JavaScript**

```javascript
async function call(url, init) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch(url, init);
    if (response.status !== 429) return response;
    const wait = Number(response.headers.get("retry-after")) || 1;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Rate limited");
}
```

**遵循 retry-after: Python**

```python
import time

def call(method, url, **kwargs):
    for attempt in range(5):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("retry-after", 1)))
    raise RuntimeError("Rate limited")
```

请将突发流量分散到不同时间；优先使用 [Webhook](https://fileverity.com/zh/docs/webhooks.md) 而非密集的轮询循环，并在[分析](https://fileverity.com/zh/docs/analyses.md)中使用 `Prefer: wait` 代替轮询。资源繁忙时，`POST /analyses` 会返回 `503 service_unavailable` 及 `retry-after`；参见[服务繁忙时](https://fileverity.com/zh/docs/analyses.md#busy)。

## 其他响应头

| 请求头 | 出现位置 | 含义 |
| --- | --- | --- |
| `x-request-id` | 所有响应 | 请求 ID，错误响应体中也包含该 ID。 |
| `cache-control: no-store` | 所有响应 | API 响应不会被缓存。 |
| `preference-applied` | `POST /analyses` | 您的 `Prefer` 请求头生效时，值为 `wait=N`。 |
| `idempotent-replayed` | POST 接口 | 当响应是已保存响应的重放时为 `true`。参见[幂等性](https://fileverity.com/zh/docs/idempotency.md)。 |
| `x-evidence-included` | `GET /analyses/{id}/report.pdf` | 文档证据已过期、PDF 中不再包含证据时为 `false`。 |

## 您发送的请求头

- `Authorization: Bearer <key>`：必填。参见[身份验证与密钥](https://fileverity.com/zh/docs/authentication.md)。
- `Content-Type: application/json` 用于 JSON 请求体；`multipart/form-data` 用于 `POST /files` 上传。
- `Idempotency-Key`：可选，用于 POST 请求。
- `Prefer: wait=N`：可选，用于 `POST /analyses`。

示例：`curl -i https://api.fileverity.com/v1/models -H "Authorization: Bearer $FILEVERITY_API_KEY"` 会显示所有响应头。