Handlers for rate-limited APIs

[clarfonthey]

By default, reqwest should automatically handle HTTP 429 errors, but we will also want the ability for users to easily add custom rate-limit handlers similarly to the way that we can configure redirect handlers.

For example, an API might return a JSON blob stating that the request was rate-limited plus some 400-level error. We would want to be able to handle that.

See brson/rust-cookbook#93 for some more discussion on this.

[seanmonstar]

Hm, I don't quite get what is desired here. Would you have some example code that would do this, what exactly reqwest would be doing?

[clarfonthey]

Basically, right now, if a request returns a 300-level request, then the redirect handler will decide whether to create a new request to the new URL.

This would propose adding an additional handler which will respond to 400- and 500-level requests, which will decide whether to retry the request and after how long it should be retried. By default, this should only respond to HTTP 429 requests, which will be retried after the number of seconds listed in the Retry-After header.

However, there are potentially other types of requests to consider. For example, a non-standard API might return a 400 request with a JSON blob that states that the user is being rate-limited. A custom handler could inspect this blob and choose to retry based upon this value. It could also limit the number of retries.

Twitter uses the 420 error with custom headers instead. Also, I believe that GitHub uses another non-standard method. Someone might also want to create a handler that responds to 504 requests by retrying after a minute. There's lots of different options.

[seanmonstar]

Retry after so many seconds... So what would it do? Sleep the thread?

[clarfonthey]

Pretty much. This could be factored into a total timeout for the request; so if a request expects to work within a minute, then any retries would be factored into it.

The crate using reqwest can add its own rate-limiting for sending requests, but on the off-chance that an API just happens to go over the rate limit, it's best to deal with it how the RFC states instead of just marking it as an error.

[seanmonstar]

Considering that no one seems to follow any spec, and that it'd be sleeping a thread, it kind of feels out of scope for reqwest. It shouldn't be too difficult for anyone to handle rate limiting themselves, specific to the API they are talking to.

[clarfonthey]

That is fair! I'll close this issue for now and people can continue this in the other thread.