Skip to main content
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 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.
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.
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 (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.

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:
429 Too Many Requests
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

1

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.
2

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.
3

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. 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.
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
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.