Thats unexpected from the docs... Max amount of time one waits should be documented or configurable IMO.
Also, retry-after can contain Date which would cause next line to crash

Ah, it wouldn't crash because length would be >= 3, my bad. But anyways, shouldn't that behavior be documented in more detail like (e.g.: "retry-after Date is not respected, retry-after Seconds is respected to at max 99 seconds")?

I agree, this part needs some more polishing. Thanks for bringing attention.

Maybe we could make automatic retry only be automatic if retry-after time is reasonable short. This would behave a little different from now, but we could argue that this would be less surprising. I do not know the reason for 99 s but that seems unreasonable long and was not documented.

Ideally, I'd want something like {autoretry, #{max_retries=>X, max_waiting_time=>Y}}. Default would be {max_retries=>0, max_waiting_time=>Y}. Capping max_retries and max_waiting_time would prevent possible "infinite wait".

What's "reasonable short" is very dependent on the application and this way we let the user specify the terms.

Hum well maybe {autoretry, timeout()} would make sense instead of having to many knobs ! Httpc can then itself handle how many possible retries it can have before giving up, and a timeout of zero imply no automatic retries. I agree that reasonable short is hard to determine especially for the library, but due to backwards compatibility we might still want to settle for some fairly short default timeout.

Works for me, but what's unfortunate is that HTTP retry-after is in seconds while timeout often refers to milliseconds so having something like #{max_waiting_seconds => non_neg_integer()} instead of timeout() would clarify the API.

We can also just stick to {autoretry, timeout()} but we must be explicit in the docs that this timeout means seconds.