Bỏ qua để đến nội dung chính
LeoNex News

Trả về gì khi bị giới hạn tốc độ (HTTP 429): Retry-After, header RateLimit và quota

Sơ đồ phản hồi 429 với các header giới hạn tốc độ, nhánh thử lại và nhánh hết quota có thời điểm đặt lại.
Trong bài này

Mã trạng thái 429 một mình cho client biết rất ít. Điều quyết định client có tự phục hồi được hay không là phần đi kèm: giá trị Retry-After, cặp trường RateLimit, và phần thân nói rõ giới hạn nào bị chạm. Bài viết này chỉ bàn về phản hồi: nên đặt gì vào đó và client nên làm gì với nó, không bàn về cách đếm request.

Mã 429 hứa hẹn điều gì và Retry-After nên viết thế nào

RFC 6585 định nghĩa 429 chỉ trong vài câu: phản hồi nên có thông tin giải thích tình trạng, và có thể kèm header Retry-After cho biết cần chờ bao lâu. Tài liệu này không quy định máy chủ nhận diện người dùng hay đếm request ra sao. Vì vậy mã trạng thái không nói lý do và cũng không nói chờ bao lâu.

RateLimit-Policy và RateLimit giúp client chậm lại trước khi bị từ chối

Retry-After chỉ nói về quá khứ: bạn đã bị từ chối, hãy quay lại sau. Bản nháp IETF về header giới hạn tốc độ, draft-ietf-httpapi-ratelimit-headers, thêm hai trường giúp client giảm tốc trước khi bị từ chối. Bản -11 phát hành ngày May 23, 2026 vẫn là bản mới nhất tại thời điểm viết và vẫn chỉ là bản nháp, chưa phải RFC.

  • RateLimit-Policy mô tả chính sách: hạn mức q trên mỗi cửa sổ w giây.

  • RateLimit báo vị trí hiện tại của client: còn r đơn vị, và t là số giây trong đó client chỉ dùng được tối đa r.

Token bucket không khớp hoàn toàn với mô hình q mỗi w giây. Tác giả gửi kích thước bucket làm q và thời gian nạp đầy từ trống làm w. Với bucket đã cạn, t là thời gian đến khi có lại một token, con số này chính xác. Với bucket còn token thì không có đáp án chính xác vì nó vẫn đang nạp trong lúc client tiêu thụ, nên t là thời gian đến khi đầy; client coi r là mức có thể tiêu ngay sẽ an toàn.

Rate limit và quota cần hai câu trả lời khác nhau

Rate limit nói về tốc độ và tự hồi phục sau vài giây, nên thử lại là đúng. Quota nói về khối lượng trong một kỳ thanh toán, ví dụ 1,000 request mỗi tháng ở gói miễn phí. Thử lại khi hết quota là vô ích cho đến khi kỳ kết thúc, hoặc khách nâng gói hay mua thêm credit. Mỗi tình huống nên có mã trạng thái hoặc mã lỗi riêng để client phân biệt mà không phải đoán.

  • Chạm rate limit: trả 429, Retry-After là số giây đến khi có lại token, lỗi rate_limited.

  • Hết quota ở gói dừng tại giới hạn: trả 429, Retry-After là số giây đến khi kỳ kết thúc, lỗi quota_exceeded kèm resets_at trong bản demo.

  • Hết credit trả trước: trả 402, không có Retry-After vì chờ cũng vô ích, lỗi insufficient_credits.

  • Khách bị đình chỉ: trả 403, không có Retry-After, lỗi consumer_suspended.

  • Dịch vụ quota không truy cập được và đã chọn từ chối thay vì cho request đi qua: trả 503, áp dụng backoff của client, lỗi quota_unavailable.

Về việc có đưa quota tháng vào RateLimit-Policy hay không, bản nháp cho phép, nhưng tác giả không làm vậy. Quota được đặt lại vào một thời điểm cố định, và chính bản nháp cảnh báo ở mục 8.5 rằng thời điểm đặt lại cố định khiến mọi client bị chặn quay lại cùng lúc. Vì thế phản hồi quota dùng Retry-After cộng resets_at trong thân, và client coi đó là sự kiện kinh doanh, không phải việc thử lại.

Thứ tự kiểm tra và phía client

Thứ tự kiểm tra cũng quan trọng: máy chủ kiểm tra quota trước rate limit. Nếu khách đã dùng hết tháng mà còn gửi quá nhanh, quota mới là lý do họ cần nghe; câu trả lời chờ 1 giây chỉ đẩy họ vào vòng lặp kết thúc ở quota. Chỉ phản hồi thành công mới tiêu hao quota hoặc credit, và request bị từ chối không lấy token khỏi bucket.

Về phía client, phần tiếp theo của bài hướng tới nguyên tắc thử lại với thời gian chờ ngắn và dừng khi thời gian chờ dài. Đoạn văn bản được cung cấp dừng ngay ở tiêu đề này nên không có thêm chi tiết nào để trình bày.

Điểm chính

Nguồn tham khảo

Các nguồn mà bài viết này dựa vào.

  1. What to send back with a 429: Retry-After, RateLimit headers and telling a rate limit apart from a quota (mở trong tab mới) — Viblo

Xem thêm trong Software Engineering

Mô-đun zlib-rs đặt phía trên bộ máy CPython, cạnh khe dự phòng C, minh họa đề xuất backend Rust tùy chọn cho Python 3.16.
SOFT-ENG Software Engineering

Rust vào CPython? Thảo luận tại Python Language Summit

David Hewitt, đại diện nhóm dự án Rust for CPython, đã quay lại Python Language Summit để hỏi các core developer của Python muốn gì ở Rust. Ông đưa ra lộ trình theo từng giai đoạn, tiêu chí thành công và đề xuất bắt đầu bằng một backend Rust tùy chọn cho module zlib. Mục tiêu dài hạn là đưa Rust…

6 phút đọc

Núm chỉnh phiên bản chuyển từ 14.6 sang 15.6, với các chi tiết tượng trưng cho tính năng JavaScript, thay đổi hành vi và giới hạn bộ nhớ.
SOFT-ENG Software Engineering

Những thay đổi V8 đáng chú ý từ Node.js 26 lên 27

Bản Node.js 27 Alpha nâng cấp V8 lên phiên bản 15.6, từ 14.6 trong Node.js 26. Việc nâng cấp mang đến một số tính năng ngôn ngữ JavaScript mới, nhiều thay đổi về hành vi, cải thiện hiệu năng và điều chỉnh về bộ nhớ. Một số thay đổi có thể làm hỏng mã vốn dựa vào hành vi cũ, nên đáng để lập trình…

4 phút đọc

Bản tin qua email

Nhận tuyển chọn bài viết mới của LeoNex News qua email.

Chúng tôi chỉ dùng địa chỉ này để gửi bản tin.

Nhận tuyển chọn bài viết mới của LeoNex News qua email. Bạn sẽ nhận một email xác nhận; đăng ký chỉ có hiệu lực sau khi bạn xác nhận. Mỗi email đều có liên kết hủy đăng ký. Xem chính sách quyền riêng tư