Add reset response header for all rate limited endpoints

[ErikKalkoken]

Feature Request

It would be nice if rate limited endpoints would also return a reset header in the response.

The reset header should indicate how many seconds a client has to wait until at least 5 additional tokens are available for the current bucket. It should be 5, because that is the maximum token cost for making a another request.

This information would allow a clients to retry when reaching a lower threshold of remaining tokens for the current bucket (e.g. 10). Without that information it is difficult for a client to determine the correct time for a retry, i.e. when the next 5 tokens will be available.

Some may argue that a client can just keep track of the timestamps of all requests and then calculate this information. In my opinion it is not that easy, though. Client and server can occasionally de-synchronize (e.g after client or server restarts), so the client needs some sophisticated logic to detect and re-synchronize with the server for this to work.

Without a reset header most clients will probably just wait for a 429 to occur an then use the retry after header.

Use case

API users who want to reduce the risk of generating 429s.

Authentication

N/A

Example return

Example header for the status endpoint indicating that +5 = 35 tokens will be available in 30 seconds.

x-ratelimit-group: status
x-ratelimit-limit: 600/15m
x-ratelimit-remaining: 30
x-ratelimit-used: 570
x-ratelimit-reset: 30

Checklist

Check all boxes that apply to this issue:

• Feature request description is provided
• Use case exists
• Feature requires a new route
• Feature adds data to existing route
• Feature requires new auth scope
• Feature can reuse existing scope
• Feature does not require auth
• Meta feature, applies to all routes

Update

After further investigation I discovered that for some clients it is not only difficult, but impossible to calculate when the next 5 tokens will be available. This makes the feature request even more important.

This affects all desktop and mobile applications. When running the same app in parallel on different devices, each will consume tokens from the same rate limit bucket. However each app instance can't know when the requests from other client happened and therefore can not calculate when the next 5 tokens will be available.