When rate limiting is hit return return a Retry-After header

Contribute Feature
5

Good suggestion!

In between time, the IETF has standardized the headers for informing calling programs about rate limiting; see RateLimit Header Fields for HTTP. Our software uses them for a range of rate limiters (see https://forums.invantive.com/t/fair-use-daily-limits-for-a-better-user-experience/3767).

In our case it would help definitely when Discourse would return rate limit information through headers; the programs don’t have access to the configuration file and we have no exact idea without asking what the definitions are. Nor can our calling software try to evade a 429 by trying alternatives when the rate limit is in near sight.

V3 Status

On v3, the following headers are present that provide some guidance:

  • Retry-After: number of seconds after which the rate limit window expires and a new set of API calls is allowed
  • Discourse-Rate-Limit-Error-Code: an indication what type of rate limit is hit (such as admin_api_key_rate_limit or ip_10_secs_limit).

On HTTP 429, also the payload contains some hints, but nothing additional compared to the HTTP headers:

{
    "errors": [
        "i18n text"
    ],
    "error_type": "rate_limit",
    "extras": {
        "wait_seconds": 21,
        "time_left": "21 seconden"
    }
}

Note that these headers are only returned upon 429. It is not possible to predict an upcoming failure to back off a little.