Handling Rate-Limits: Sleep confusing documentation

[maximehinnekens]

The sleep() section comes right after the "Handling Rate Limits Being Exceeded" section, this makes a confusing outcome expectation of using the sleep() method on a limit,

This is the section about the Exception:

Handling Rate Limits Being Exceeded

When a rate limit has been reached, Saloon will throw a RateLimitReachedException. This exception contains a getLimit method which may be used to see the limit that has thrown the exception and see the number of seconds to wait before a request can be sent again. This can be done with a simple try-catch approach or if you are using the provided Laravel job middleware, then you can instruct your jobs to wait until the limit has been lifted.

Try/Catch

As mentioned above, Saloon will throw an exception if a rate limit is reached or if the API returns a 429: Too Many Requests response. You could use a try/catch block to catch the exception and do something with the limit. For example, you may return an error to your users to let them know how long they need to wait - or you might retry the request later. If you are using Saloon in a context of a queued process, then you may want to retry the queued job in the future, from the remaining seconds.

This explains how exceeding a defined or detected limit throws an exception. This is correctly documented.
However, right after this, the following sleep section is written:

Sleep

If would rather Saloon didn't throw an exception, you can use the sleep method when defining a limit. When using the sleep method, an exception won't be thrown. Instead, Saloon will wait the remaining number of seconds before a request is attempted again.

use Saloon\RateLimitPlugin\Limit;

protected function resolveLimits(): array
{
    return [
        Limit::allow(60)->sleep(),
    ];
}

This made me very confused as the sleep does not prevent an Exception when a 429 is detected, only when a manually registered limit is hit. I'm not sure if this is indeed expected behaviour or a bug (would be nice if it could sleep when 429 with Retry-After is detected). I've tested it myself the last half hour and the sleep only works on the manual limits. Moreover, the example given for sleep() does not work, it will fail to store the limit without any time interval chained on it.

Using versions:
saloonphp/laravel-plugin v3.0.0,
saloonphp/rate-limit-plugin v2.0.0,
saloonphp/saloon v3.10.0