RoomScope

Cập nhật lần cuối

Giới hạn tốc độ

Có hai thứ giới hạn lượng dữ liệu bạn đọc được: tốc độ request của mỗi API key, và số credit trong ví. Chạm giới hạn thứ nhất sẽ nhận 429; hết thứ hai sẽ nhận 402.

Tốc độ request

Giới hạn áp dụng cho từng API key; gói của workspace quyết định các con số. Mỗi key có một giới hạn theo giây (cửa sổ trượt một giây) và một hạn mức hằng ngày, reset lúc nửa đêm UTC. Phiên dashboard không bị giới hạn tốc độ.

GóiRequest mỗi giâyRequest mỗi phútRequest mỗi ngàyKey đang hoạt động
Free1605,0001
Starter530015,0003
Pro201,200100,00010
Scale603,600400,00025
Agency / Enterprise1509,0001,200,000không giới hạn

Workspace còn có giới hạn theo phút, dùng chung cho mọi key: một cửa sổ một phút cố định theo UTC. Vượt giới hạn sẽ trả 429 với code minute_rate_limit_exceeded và Retry-After đếm tới phút kế tiếp; header X-RateLimit-Minute-Limit và X-RateLimit-Minute-Remaining cho biết phần còn lại.

Request bị từ chối vì thiếu scope hoặc module (403) không bị tính; mọi request đã qua bước xác thực đều bị tính, bất kể kết quả ra sao.

Header

Mọi response đã đi qua bộ giới hạn đều mang theo hạn mức còn lại. X-RateLimit-Limit và X-RateLimit-Remaining mô tả cửa sổ theo giây; cặp Daily xuất hiện khi key có hạn mức hằng ngày.

http
HTTP/2 200X-RateLimit-Limit: 20X-RateLimit-Remaining: 19X-RateLimit-Minute-Limit: 1200X-RateLimit-Minute-Remaining: 1187X-RateLimit-Daily-Limit: 100000X-RateLimit-Daily-Remaining: 98431

Một response 429 trông như thế nào

Request bị chặn do vượt tốc độ trả về 429 với code rate_limit_exceeded, envelope lỗi chuẩn và header Retry-After tính bằng số giây nguyên. Hãy chờ ít nhất chừng đó trước khi thử lại; tăng thời gian chờ theo cấp số nhân nếu bạn tiếp tục bị chặn.

429 Too Many Requests
HTTP/2 429Content-Type: application/jsonRetry-After: 1 {"code":"rate_limit_exceeded","message":"API key rate limit exceeded.","requestId":"3f2b6c1e-…","retryable":true}

Khi đã dùng hết hạn mức trong ngày, API trả về 429 với code daily_quota_exceeded và một Retry-After đếm tới nửa đêm UTC. Các header hạn mức không được gửi kèm trên chính response 429 đó.

Credit

Độc lập với tốc độ request, mọi lượt đọc đều được tính bằng credit từ ví của workspace. Đọc dữ liệu cache có giá thấp; request cần thu thập dữ liệu mới tốn nhiều hơn (xem Credit). Khi chạm hạn mức, mọi lệnh gọi có tính phí, kể cả đọc dữ liệu cache, đều trả về 402 với code credit_cap_exceeded.

Giữ dưới giới hạn
Hãy cache response phía bạn ít nhất bằng chu kỳ làm mới của bảng (bảng theo giờ thay đổi mỗi giờ một lần), theo dõi resetAt thay vì dùng bộ hẹn giờ cố định, và ưu tiên webhook thay vì polling cho các sự kiện LIVE.
Trang này có hữu ích không?