Rate Limit

_{Published: 27 January 2024}

Known Uses

The Rate Limit pattern is commonly used in Dutch government APIs, particularly in open data government services. Rate Limits are a standard practice for these types of APIs and are technically implemented. However, client awareness and (how much of the Rate Limit is used?) is sometimes poorly managed. Often, one must settle for information about the Rate Limit on the developer portal or gateway, and limit headers in responses are not commonly implemented. The Rate Limit pattern is less frequently utilized in the Dutch energy sector because there are fewer customer public APIs that are internet-facing.

Some Dutch government known uses (to mention only a few):

• The KNMI (Royal Netherlands Meteorological Institute) Data Platform provides access to open datasets maintained or generated by the KNMI on weather, climate and seismology. This platform grants access via registered API Keys and anonymous keys. Anonymous keys provide unregistered access to the Open Data API. To ensure fair usage and to be able to control the operational costs of KNMI Data Platform, the number of API calls is limited with different limits for registered and anonymous keys. Note that anonymous users share these limits with all other active users of the anonymous API key. On the portal, the Rate Limit per registration policy is presented:
  • https://developer.dataplatform.knmi.nl/open-data-api#token
  • https://developer.dataplatform.knmi.nl/edr-api No Rate Limit headers are provided in these APIs.
• An example is the BAG API (BAG stands for Basisregistratie Adressen en Gebouwen and translates to Basic Registration of Addresses and Buildings in the Netherlands): This API uses two Rate Limit scenarios:
  • Kadaster-RateLimit-DayLimit: allowed amount of requests per day;
  • RateLimit-Limit: allowed amount of requests per second; In this example, limit headers are typically returned with every request, not exclusively with a 429 HTTP status code.
• In the DSO API register (DSO: Environment and Planning Act of the Netherlands), which is expected to come into force on January 1, 2024, we can see an overview of APIs with allowed throttling limits (again no limit headers): https://aandeslagmetdeomgevingswet.nl/ontwikkelaarsportaal/api-register/beschikbare-api-services/.
• In the KVK (Companies listed in the Business Register) we see a combination of Rate Limit and the Pricing Plan pattern: https://developers.kvk.nl/apis/zoeken.
• OTTO Market API Developer’s Guide gives an example of Rate Limits per endpoint or partner id.

Discussion Input

Currently, there is no official, agreed-upon standard policy for usage in Dutch governmental API guidelines (as far as we know). Most APIs operate on a fair-use basis (very often a max of 100 requests per second) but without a proper description of what that entails. Usage limits are defined technically but not communicated clearly either on the portal or by headers in the API description itself.

The GitHub example presented in the book (page 414) is also used by Zalando and Otto, with the same custom HTTP headers. Besides the X-RateLimit scenario, Zalando also opts for the Retry-After scenario: a header indicating how long the client ought to wait before making a follow-up request. The reason to allow both approaches is that APIs can have different needs. For Zalando and Otto, headers MUST be used in combination with code 429. Also here: Rate Limit headers are generally returned on every request and not just on a 429:

• https://opensource.zalando.com/restful-api-guidelines/#153
• https://api.otto.de/portal/guidelines/r000014

Rate Limit is an important pattern according to OWASP “API4:2023 Unrestricted Resource Consumption”: https://owasp.org/API-Security/editions/2023/en/0xa4-unrestricted-resource-consumption/.

A nice discussion point is the question: what is the appropriate HTTP error code when a data-bound Rate Limit is violated? The 429 is used when there are too many requests, but that’s a different limit than the data-bound Rate Limit that includes response data volumes in the definition. How should one respond when the limit on data volume is surpassed? The recommended approach remains to utilize the 429 “Too Many Requests” error, supplemented with an RFC 7807 detailed explanation.

OpenAI has very good documentation on their API Rate Limit policy: https://platform.openai.com/docs/guides/rate-limits?context=tier-free.

Difference between Rate Limit and Throttling: Throttling is the action of controlling the speed or frequency of accesses, while rate limiting specifically sets a cap on the number of accesses within a defined timeframe. Throttling can involve various strategies, including rate limiting, but rate limiting is a specific form of throttling. (throttling: server side, Rate Limit client side). See https://nordicapis.com/api-rate-limiting-vs-api-throttling-how-are-they-different/.

It is interesting to see how the Rate Limit pattern relates to other patterns in the book. Since Rate Limit is an API-level pattern and the other ones listed below operate with message-Level scope (request messages in particular), it suggests a strong relationship between these two groups. Here is an attempt to overview the relations:

• Service Level Agreement (SLA): Rate Limits can be detailed in the SLA.
• API Key: identification of clients to enforce Rate Limit
• Pricing Plan: A Pricing Plan can use Rate Limits to enforce different billing levels.
• Wish List and Wish Template can influence Rate Limit since less data is transferred.
• Request Bundle can influence Rate Limit since fewer requests are required.
• API Description must/should include limit headers and status code 429. And introducing Rate Limit or modifying it in an existing contract is a breaking change.
• Conditional Request can influence Rate Limit since less data is transferred.
• Context Representation: The current state of the Rate Limit can be communicated via this pattern.

Recommended Reading

An important API security best practice is to use dynamic Rate Limits and set static Rate Limits selectively. Rate-limiting mechanisms should be much more dynamic, granular, and based on actual consumption patterns. Setting blanket static Rate Limits can result in impeded application functionality that directly impacts the organization’s business, not to mention attackers will throttle their attempts to evade those limits (source: https://salt.security/blog/api-security-best-practices).

Currently, there is no standard way for servers to communicate quotas so that clients can throttle their requests to prevent errors. Not official yet, but currently in the make is the draft RFC: RateLimit header fields for HTTP, https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-07.