> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Hạn mức yêu cầu đối với Living Security Public API, quy ước phản hồi 429 và cách thử lại bằng Retry-After.

API `/v1` áp dụng hai hạn mức yêu cầu độc lập. Một yêu cầu sẽ bị từ chối
nếu một trong hai hạn mức đã cạn.

| Hạn mức | Áp dụng cho |
| - | - |
| Theo khóa API | Mọi yêu cầu sử dụng khóa đó, từ bất kỳ địa chỉ nào |
| Theo IP máy khách | Mọi yêu cầu từ địa chỉ đó, dù đã xác thực hay chưa |

Hạn mức theo khóa đi theo khóa ở bất kỳ nơi nào khóa được sử dụng. Hạn mức theo IP
là hạn mức duy nhất đối với lưu lượng chưa xác thực và là mức trần thứ hai đối với
lưu lượng đã xác thực.

<Note>
  Các giới hạn được áp dụng trước khi xác thực, do đó các yêu cầu có thông tin xác thực không hợp lệ hoặc
  bị thiếu cũng được tính vào hạn mức của nguồn gửi. Các hạn mức bằng số cụ thể do nhà vận hành
  cấu hình và có thể thay đổi; quy ước phản hồi bên dưới là giao diện ổn định để xây dựng tích hợp.
</Note>

Xác thực bằng một trong hai dạng thông tin xác thực Basic — xem
[Khởi động nhanh](/vi/developers/v1/quickstart) (`apikey:secret` hoặc `secret:`).
Đặt `BASE` thành máy chủ theo khu vực của tổ chức — xem
[Khu vực](/vi/developers/v1/regions).

## Phản hồi 429

Khi một hạn mức đã cạn, API trả về `429 Too Many Requests` kèm
tiêu đề `Retry-After` (tính bằng giây) và nội dung problem-details tiêu chuẩn:

```json 429 Too Many Requests theme={null}
{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the Retry-After interval.",
  "code": "rate_limited",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/rate_limited",
  "retryable": true
}
```

Phản hồi không cho biết hạn mức nào đã cạn. Hãy xử lý mọi phản hồi `429` theo
cùng một cách: chờ, sau đó thử lại.

## Xử lý phản hồi 429

<Steps>
  <Step title="Tuân thủ Retry-After">
    Chờ ít nhất số giây được nêu trong tiêu đề `Retry-After` trước khi
    thử lại. Thử lại sớm hơn chỉ tiêu tốn thêm hạn mức cho các yêu cầu sẽ
    bị từ chối.
  </Step>

  <Step title="Giãn cách theo cấp số nhân khi lặp lại">
    Nếu một lần thử lại tiếp tục bị từ chối, hãy tăng thời gian giãn cách và thêm độ trễ ngẫu nhiên (jitter)
    để các worker song song không thử lại đồng loạt. Không được rút ngắn `Retry-After` của máy chủ để phù hợp với mức giới hạn
    cục bộ. Nếu máy chủ yêu cầu bạn chờ lâu hơn mức hạn mức thử lại của bạn cho phép,
    hãy dừng lại và lên lịch thực hiện công việc vào lúc khác.
  </Step>

  <Step title="Làm đều tốc độ yêu cầu">
    Nên duy trì tốc độ yêu cầu ổn định thay vì gửi dồn dập. Đối với việc đọc hàng loạt, hãy dùng kích thước trang tối đa
    (`limit=500`) để duyệt hết tập dữ liệu với ít yêu cầu hơn — xem
    [phân trang](/vi/developers/v1/pagination). Khi nhiều lượt duyệt danh sách chạy
    song song (ví dụ các bảng Power BI), hãy giữ mức đồng thời ở mức vừa phải và tuân thủ
    `Retry-After` để một phản hồi 429 tạm thời không làm hỏng toàn bộ lượt làm mới.
  </Step>
</Steps>

Ví dụ này chỉ thử lại các phản hồi `429` đối với yêu cầu **GET**, với tối đa
năm lần thử và chờ tối đa 60 giây giữa các lần thử. Ví dụ dừng ngay
khi gặp các lỗi khác. Lỗi hết thời gian chờ mạng được chuyển tiếp đến bên gọi. Hãy cấu hình
thời gian chờ và hạn mức thử lại cho phù hợp với khối lượng công việc của bạn. `requests` hiểu thời gian chờ đọc
là khoảng thời gian nhàn rỗi tối đa khi nhận dữ liệu, không phải thời hạn tổng thể.

Tải `LIVING_SECURITY_API_KEY` từ trình quản lý bí mật của bạn. Cài đặt `requests`
trước khi chạy ví dụ này. Gọi `get_with_retry("/organization")` để sử dụng.

```python Python theme={null}
import os
import random
import time
import requests

# US: BASE = "https://api.us-east-1.livingsecurity.ai/v1"
BASE = "https://api.eu-west-1.livingsecurity.ai/v1"
AUTH = ("apikey", os.environ["LIVING_SECURITY_API_KEY"])

def get_with_retry(path, params=None, max_attempts=5):
    if not 1 <= max_attempts <= 5:
        raise ValueError("max_attempts must be between 1 and 5")
    for attempt in range(max_attempts):
        response = requests.get(
            f"{BASE}{path}", auth=AUTH, params=params,
            headers={"Living-Security-Version": "2026-07-01"},
            timeout=(5, 30), allow_redirects=False,
        )
        if response.status_code != 429:
            response.raise_for_status()
            if not 200 <= response.status_code < 300:
                raise RuntimeError("Unexpected redirect; check your regional API URL")
            return response

        # The API returns Retry-After as a whole number of seconds.
        raw_wait = response.headers.get("Retry-After", "")
        request_id = response.headers.get("Request-Id", "unknown")
        response.close()
        if attempt == max_attempts - 1:
            raise RuntimeError(f"Retry budget exhausted; request_id={request_id}")
        if not raw_wait.isascii() or not raw_wait.isdigit() or len(raw_wait) > 6:
            raise RuntimeError(f"Invalid Retry-After; request_id={request_id}")

        wait = max(int(raw_wait), min(2 ** attempt, 30))
        delay = wait + random.uniform(0, 1)
        if delay > 60:
            raise RuntimeError(f"Retry-After exceeds wait budget; request_id={request_id}")
        time.sleep(delay)
```

Không sao chép vòng lặp này sang thao tác ghi. Lỗi hết thời gian chờ sau một thao tác ghi có thể
có nghĩa là máy chủ đã ghi nhận thao tác trước khi kết nối thất bại. Chỉ lặp lại thao tác ghi
khi tài liệu tham chiếu của thao tác đó nêu rõ tính idempotent, đồng thời giữ nguyên
khóa và payload. Nếu không, hãy đối chiếu trạng thái tài nguyên trước khi thử lại.

## Lịch làm mới khuyến nghị

Hãy xác định tần suất làm mới dựa trên hạn mức khóa và kích thước trang của bạn. Việc tải toàn bộ dữ liệu
lịch sử của một tập dữ liệu lớn chỉ là chi phí một lần; nên dùng các khoảng thời gian tăng dần cho
các lần làm mới ở trạng thái ổn định để mỗi lần chạy luôn thấp hơn nhiều so với hạn mức. Luôn đặt
`limit=500` một cách tường minh — giá trị mặc định là 25 sẽ làm tăng số lượng yêu cầu.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.