Telm đo lường API theo hai cách: một giới hạn tốc độ mỗi phút (một trần bùng phát) và một hạn mức hằng ngày (tổng ngân sách của bạn cho ngày UTC). Cả hai đều thay đổi theo gói. Mỗi phản hồi được đo lường trả về X-Quota-Limit, X-Quota-Used và X-Quota-Reset để bạn luôn biết ngân sách còn lại của mình, và cả hai giới hạn đều trả về 429 kèm một header Retry-After khi bị vượt.
1Hai giới hạn: tốc độ mỗi phút và hạn mức hằng ngày
Có hai trần riêng biệt. Giới hạn tốc độ mỗi phút giới hạn số yêu cầu bạn có thể thực hiện trong bất kỳ một phút nào, làm mượt các đợt bùng phát. Hạn mức hằng ngày là ngân sách tổng thể của bạn: nó giới hạn số lệnh gọi được đo lường bạn có thể thực hiện trong suốt cả ngày UTC.
Chúng độc lập với nhau. Bạn có thể chạm giới hạn mỗi phút trong khi vẫn còn dư dả hạn mức hằng ngày (bạn chỉ đơn giản là gửi quá nhanh), hoặc cạn hạn mức hằng ngày trong khi còn dưới xa giới hạn mỗi phút (bạn đã dùng hết ngày). Cả hai đều trả về trạng thái 429, nhưng vì các lý do khác nhau — hãy kiểm tra mã lỗi trong thân để phân biệt chúng.
- Giới hạn tốc độ mỗi phút — một trần bùng phát, đặt lại mỗi phút.
- Hạn mức hằng ngày — tổng số lệnh gọi được đo lường trong ngày, đặt lại vào nửa đêm UTC.
- Hạn mức được tính một lần cho mỗi tài khoản, chia sẻ trên tất cả các khóa của bạn.
2Hạn mức hằng ngày theo gói
Hạn mức hằng ngày của bạn là số lệnh gọi API được đo lường bạn có thể thực hiện mỗi ngày UTC, và nó phụ thuộc vào gói của bạn. Bộ đếm được chia sẻ trên tất cả các khóa của bạn và theo gói tốt nhất trong số các nhóm bạn quản trị — nếu không có gói đăng ký trả phí, bạn ở bậc Free.
Khung thời gian là ngày lịch UTC, nên bộ đếm đã dùng của bạn đặt lại về không vào nửa đêm UTC. Một lần kiểm tra spam hàng loạt tốn một lệnh gọi cho mỗi mục trong lô, chứ không phải một lệnh gọi cho cả yêu cầu.
- Free — 100 lệnh gọi mỗi ngày.
- Basic — 1.000 lệnh gọi mỗi ngày.
- Pro — 10.000 lệnh gọi mỗi ngày.
- Business — 50.000 lệnh gọi mỗi ngày.
3Giới hạn tốc độ mỗi phút theo gói
Bên cạnh hạn mức hằng ngày, mỗi khóa API bị giới hạn một số yêu cầu mỗi phút tùy theo bậc gói của nó. Đây là một giới hạn làm mượt: nó ngăn một client đơn lẻ gửi một đợt tăng vọt lớn trong một giây, ngay cả khi ngân sách hằng ngày còn lâu mới hết.
Riêng biệt, các trần rộng theo mỗi IP và mỗi tài khoản áp dụng trên toàn API để giữ nền tảng ổn định. Trong sử dụng bình thường — các yêu cầu đều đặn, có nhịp — bạn sẽ không bao giờ chạm tới chúng; chúng chỉ kích hoạt khi có các đợt bùng phát lạm dụng.
- Free và Basic — 60 yêu cầu mỗi phút.
- Pro — 600 yêu cầu mỗi phút.
- Business — 1.800 yêu cầu mỗi phút.
- Hãy rải các yêu cầu ra thay vì bắn tất cả cùng một lúc.
4Đọc ngân sách còn lại của bạn
Bạn không bao giờ phải đoán còn lại bao nhiêu hạn mức. Mỗi phản hồi được đo lường — thành công hay thất bại — đều bao gồm ba header: X-Quota-Limit (giới hạn hằng ngày của bạn), X-Quota-Used (bạn đã dùng bao nhiêu lệnh gọi hôm nay), và X-Quota-Reset (thời điểm, theo UTC, khi bộ đếm đặt lại).
Các endpoint kiểm tra spam cũng lặp lại chính những con số đó bên trong thân phản hồi dưới một đối tượng quota, nên bạn có thể đọc ngân sách còn lại mà không cần phân tích các header. Hãy dùng chúng để điều tiết nhịp yêu cầu của mình và để tự cảnh báo trước khi bạn hết.
- X-Quota-Limit — giới hạn lệnh gọi hằng ngày của bạn.
- X-Quota-Used — số lệnh gọi đã dùng đến nay trong hôm nay.
- X-Quota-Reset — thời điểm đặt lại theo UTC (RFC 3339).
- Các phản hồi kiểm tra spam cũng bao gồm một đối tượng quota với những trường tương tự.
5Điều gì xảy ra tại 429
Khi bạn vượt qua một trong hai giới hạn, API trả về HTTP 429 kèm một header Retry-After cho bạn biết cần chờ bao nhiêu giây. Với giới hạn tốc độ mỗi phút, Retry-After khoảng một phút. Với hạn mức hằng ngày, thân mang một mã daily_quota_exceeded cộng với gói của bạn, giới hạn, số đã dùng, thời điểm đặt lại, và một gợi ý nâng cấp, còn Retry-After đếm ngược tới nửa đêm UTC.
Cách đúng để xử lý 429 là lùi lại và thử lại sau độ trễ Retry-After, không phải nện dồn dập vào endpoint. Các client cư xử tốt đọc header và tạm dừng; các client cứ thử lại ngay lập tức thì chỉ đơn giản là tiếp tục bị chặn.
- 429 rate_limit_exceeded — bạn gửi quá nhanh; hãy chờ khoảng một phút.
- 429 daily_quota_exceeded — ngày đã dùng hết; hãy chờ tới lần đặt lại UTC hoặc nâng cấp.
- Luôn tôn trọng header Retry-After trước khi thử lại.