draft-ietf-httpapi-ratelimit-headers-10.unpg.txt   draft-ietf-httpapi-ratelimit-headers-latest.txt 
HTTPAPI Working Group R. Polli HTTPAPI Working Group R. Polli
Internet-Draft Team Digitale, Italian Government Internet-Draft Team Digitale, Italian Government
Intended status: Standards Track A. Martinez Intended status: Standards Track A. Martinez
Expires: March 31, 2026 Red Hat Expires: April 16, 2026 Red Hat
D. Miller D. Miller
Microsoft Microsoft
September 27, 2025 October 13, 2025
RateLimit header fields for HTTP RateLimit header fields for HTTP
draft-ietf-httpapi-ratelimit-headers-10 draft-ietf-httpapi-ratelimit-headers-latest
Abstract Abstract
This document defines the RateLimit-Policy and RateLimit HTTP header This document defines the RateLimit-Policy and RateLimit HTTP header
fields for servers to advertise their quota policies and the current fields for servers to advertise their quota policies and the current
service limits, thereby allowing clients to avoid being throttled. service limits, thereby allowing clients to avoid being throttled.
About This Document About This Document
This note is to be removed before publishing as an RFC. This note is to be removed before publishing as an RFC.
skipping to change at line 52 skipping to change at page 2, line 7
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 31, 2026. This Internet-Draft will expire on April 16, 2026.
Copyright Notice Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Goals 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Notational Conventions 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. Terminology 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. RateLimit-Policy Field 3. RateLimit-Policy Field . . . . . . . . . . . . . . . . . . . 6
3.1. Quota Policy Item 3.1. Quota Policy Item . . . . . . . . . . . . . . . . . . . . 6
3.1.1. Quota Parameter 3.1.1. Quota Parameter . . . . . . . . . . . . . . . . . . . 7
3.1.2. Quota Unit Parameter 3.1.2. Quota Unit Parameter . . . . . . . . . . . . . . . . 7
3.1.3. Window Parameter 3.1.3. Window Parameter . . . . . . . . . . . . . . . . . . 7
3.1.4. Partition Key Parameter 3.1.4. Partition Key Parameter . . . . . . . . . . . . . . . 8
3.2. RateLimit Policy Field Examples 3.2. RateLimit Policy Field Examples . . . . . . . . . . . . . 8
4. RateLimit Field 4. RateLimit Field . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. Service Limit Item 4.1. Service Limit Item . . . . . . . . . . . . . . . . . . . 9
4.1.1. Remaining Parameter 4.1.1. Remaining Parameter . . . . . . . . . . . . . . . . . 9
4.1.2. Reset Parameter 4.1.2. Reset Parameter . . . . . . . . . . . . . . . . . . . 9
4.1.3. Partition Key Parameter 4.1.3. Partition Key Parameter . . . . . . . . . . . . . . . 10
4.2. RateLimit Field Examples 4.2. RateLimit Field Examples . . . . . . . . . . . . . . . . 10
5. Problem Types 5. Problem Types . . . . . . . . . . . . . . . . . . . . . . . . 10
5.1. Quota Exceeded 5.1. Quota Exceeded . . . . . . . . . . . . . . . . . . . . . 10
5.2. Temporary Reduced Capacity 5.2. Temporary Reduced Capacity . . . . . . . . . . . . . . . 11
5.3. Abnormal Usage Detected 5.3. Abnormal Usage Detected . . . . . . . . . . . . . . . . . 11
6. Server Behavior 6. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Generating Partition Keys 6.1. Generating Partition Keys . . . . . . . . . . . . . . . . 12
6.2. Performance Considerations 6.2. Performance Considerations . . . . . . . . . . . . . . . 13
7. Client Behavior 7. Client Behavior . . . . . . . . . . . . . . . . . . . . . . . 13
7.1. Consuming Partition Keys 7.1. Consuming Partition Keys . . . . . . . . . . . . . . . . 14
7.2. Intermediaries 7.2. Intermediaries . . . . . . . . . . . . . . . . . . . . . 14
7.3. Caching 7.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 15
8. Security Considerations 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15
8.1. Throttling does not prevent clients from issuing requests 8.1. Throttling does not prevent clients from issuing requests 15
8.2. Information disclosure 8.2. Information disclosure . . . . . . . . . . . . . . . . . 15
8.3. Remaining quota units are not granted requests 8.3. Remaining quota units are not granted requests . . . . . 16
8.4. Reliability of the reset parameter 8.4. Reliability of the reset parameter . . . . . . . . . . . 16
8.5. Resource exhaustion 8.5. Resource exhaustion . . . . . . . . . . . . . . . . . . . 16
8.5.1. Denial of Service 8.5.1. Denial of Service . . . . . . . . . . . . . . . . . . 17
9. Privacy Considerations 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 18
10. IANA Considerations 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
10.1. Update HTTP Field Name Registry 10.1. Update HTTP Field Name Registry . . . . . . . . . . . . 18
10.2. Update HTTP Problem Type registry 10.2. Update HTTP Problem Type registry . . . . . . . . . . . 18
10.2.1. Registration of "quota-exceeded" Problem Type 10.2.1. Registration of "quota-exceeded" Problem Type . . . 18
10.2.2. Registration of "temporary-reduced-capacity" Problem 10.2.2. Registration of "temporary-reduced-capacity" Problem
Type Type . . . . . . . . . . . . . . . . . . . . . . . . 19
10.2.3. Registration of "abnormal-usage-detected" Problem 10.2.3. Registration of "abnormal-usage-detected" Problem
Type Type . . . . . . . . . . . . . . . . . . . . . . . . 19
10.3. RateLimit quota unit registry 10.3. RateLimit quota unit registry . . . . . . . . . . . . . 19
10.3.1. Registration Template 10.3.1. Registration Template . . . . . . . . . . . . . . . 20
11. References 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1. Normative References 11.1. Normative References . . . . . . . . . . . . . . . . . . 20
11.2. Informative References 11.2. Informative References . . . . . . . . . . . . . . . . . 21
Appendix A. Rate-limiting and quotas Appendix A. Rate-limiting and quotas . . . . . . . . . . . . . . 21
A.1. Interoperability issues A.1. Interoperability issues . . . . . . . . . . . . . . . . . 22
Appendix B. Examples Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 23
B.1. Responses without defining policies B.1. Responses without defining policies . . . . . . . . . . . 23
B.1.1. Throttling information in responses B.1.1. Throttling information in responses . . . . . . . . . 23
B.1.2. Multiple policies in response B.1.2. Multiple policies in response . . . . . . . . . . . . 24
B.1.3. Use for limiting concurrency B.1.3. Use for limiting concurrency . . . . . . . . . . . . 25
B.1.4. Use in throttled responses B.1.4. Use in throttled responses . . . . . . . . . . . . . 26
B.2. Responses with defined policies B.2. Responses with defined policies . . . . . . . . . . . . . 26
B.2.1. Throttling window specified via parameter B.2.1. Throttling window specified via parameter . . . . . . 26
B.2.2. Dynamic limits with parameterized windows B.2.2. Dynamic limits with parameterized windows . . . . . . 27
B.2.3. Dynamic limits for pushing back and slowing down B.2.3. Dynamic limits for pushing back and slowing down . . 27
B.3. Dynamic limits for pushing back with Retry-After and slow B.3. Dynamic limits for pushing back with Retry-After and slow
down down . . . . . . . . . . . . . . . . . . . . . . . . . . 28
B.3.1. Missing Remaining information B.3.1. Missing Remaining information . . . . . . . . . . . . 29
B.3.2. Use with multiple windows B.3.2. Use with multiple windows . . . . . . . . . . . . . . 30
FAQ FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
RateLimit header fields currently used on the web RateLimit header fields currently used on the web . . . . . . . . 33
Acknowledgements Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 34
Changes Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
F.1. Since draft-ietf-httpapi-ratelimit-headers-08 F.1. Since draft-ietf-httpapi-ratelimit-headers-08 . . . . . . 35
F.2. Since draft-ietf-httpapi-ratelimit-headers-07 F.2. Since draft-ietf-httpapi-ratelimit-headers-07 . . . . . . 35
F.3. Since draft-ietf-httpapi-ratelimit-headers-03 F.3. Since draft-ietf-httpapi-ratelimit-headers-03 . . . . . . 35
F.4. Since draft-ietf-httpapi-ratelimit-headers-02 F.4. Since draft-ietf-httpapi-ratelimit-headers-02 . . . . . . 35
F.5. Since draft-ietf-httpapi-ratelimit-headers-01 F.5. Since draft-ietf-httpapi-ratelimit-headers-01 . . . . . . 35
F.6. Since draft-ietf-httpapi-ratelimit-headers-00 F.6. Since draft-ietf-httpapi-ratelimit-headers-00 . . . . . . 36
Authors' Addresses Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36
1. Introduction 1. Introduction
Rate limiting of HTTP clients has become a widespread practice, Rate limiting of HTTP clients has become a widespread practice,
especially for HTTP APIs. Typically, servers who do so limit the especially for HTTP APIs. Typically, servers who do so limit the
number of acceptable requests in a given time window (e.g. 10 number of acceptable requests in a given time window (e.g. 10
requests per second). See Appendix A for further information on the requests per second). See Appendix A for further information on the
current usage of rate limiting in HTTP. current usage of rate limiting in HTTP.
Currently, there is no standard way for servers to communicate quotas Currently, there is no standard way for servers to communicate quotas
 End of changes. 8 change blocks. 
77 lines changed or deleted 77 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/