# Giới hạn tốc độ và header

> Giới hạn tốc độ yêu cầu theo từng khóa API, các header phản hồi về giới hạn tốc độ, retry-after trên 429 và 503 cùng các header khác mà Fileverity API đặt.

Nguồn: https://fileverity.com/vi/docs/rate-limits

Mỗi khóa API có thể gửi 120 yêu cầu mỗi phút. Giới hạn được tính theo từng khung thời gian một phút và áp dụng cho mọi endpoint, kể cả các yêu cầu trả về lỗi. Khi đã dùng hết giới hạn của một khung thời gian, các yêu cầu tiếp theo nhận `429` với mã `rate_limited` cho đến khi khung thời gian được đặt lại.

Cần giới hạn cao hơn hoặc giá theo khối lượng? [Liên hệ bộ phận kinh doanh](https://fileverity.com/vi/lien-he).

## Header giới hạn tốc độ

Mọi phản hồi cho một yêu cầu đã xác thực đều kèm trạng thái của khung thời gian hiện tại của bạn:

| Header | Ý nghĩa |
| --- | --- |
| `x-ratelimit-limit-requests` | Số yêu cầu được phép trong mỗi khung thời gian. |
| `x-ratelimit-remaining-requests` | Số yêu cầu còn lại trong khung thời gian hiện tại. |
| `x-ratelimit-reset-requests` | Số giây còn lại cho đến khi khung thời gian được đặt lại. |
| `retry-after` | Chỉ có trên `429` với mã `rate_limited` và trên `503` với mã `service_unavailable`. Số giây cần chờ trước yêu cầu tiếp theo. `pending_files_limit` (cũng là `429`) không có header này. |

Các yêu cầu bị từ chối do thiếu khóa hoặc khóa không hợp lệ (`401`) không kèm các header này.

**Tuân thủ 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");
}
```

**Tuân thủ 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")
```

Hãy phân tán các đợt yêu cầu dồn dập theo thời gian, ưu tiên dùng [webhook](https://fileverity.com/vi/docs/webhooks.md) thay cho các vòng lặp truy vấn định kỳ dày đặc, và dùng `Prefer: wait` trên [lượt phân tích](https://fileverity.com/vi/docs/analyses.md) thay vì truy vấn định kỳ. Khi hệ thống đang bận, `POST /analyses` trả về `503 service_unavailable` kèm `retry-after`; xem [Khi dịch vụ đang bận](https://fileverity.com/vi/docs/analyses.md#busy).

## Các header phản hồi khác

| Header | Áp dụng cho | Ý nghĩa |
| --- | --- | --- |
| `x-request-id` | Mọi phản hồi | Mã yêu cầu, cũng có trong nội dung của các phản hồi lỗi. |
| `cache-control: no-store` | Mọi phản hồi | Phản hồi của API không bao giờ được lưu vào bộ nhớ đệm. |
| `preference-applied` | `POST /analyses` | `wait=N` khi header `Prefer` của bạn được áp dụng. |
| `idempotent-replayed` | Các endpoint POST | `true` khi phản hồi là bản phát lại đã lưu. Xem [Idempotency](https://fileverity.com/vi/docs/idempotency.md). |
| `x-evidence-included` | `GET /analyses/{id}/report.pdf` | `false` khi bằng chứng của tài liệu đã hết hạn và PDF không còn chứa phần này. |

## Header bạn gửi

- `Authorization: Bearer <key>`: bắt buộc. Xem [Xác thực và khóa API](https://fileverity.com/vi/docs/authentication.md).
- `Content-Type: application/json` cho nội dung JSON; `multipart/form-data` cho các lượt tải lên bằng `POST /files`.
- `Idempotency-Key`: tùy chọn, dùng với các yêu cầu POST.
- `Prefer: wait=N`: tùy chọn, dùng với `POST /analyses`.

Ví dụ: `curl -i https://api.fileverity.com/v1/models -H "Authorization: Bearer $FILEVERITY_API_KEY"` hiển thị toàn bộ header phản hồi.