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

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.


