Cooldown
A source that has just refused is skipped for a while rather than asked again on every buffer refill.
Because a rate limit is not an outage. The ANU public endpoint allows one request a minute and answers the second one instantly with a refusal, so without this every refill spends a round trip rediscovering that. On a metered provider it spends quota rediscovering that the quota is gone.
Choosing a value
Set it to roughly the window the provider measures, divided by how many probes you are willing to spend finding out it has recovered.
| Source | Its limit | Cooldown | Why |
|---|---|---|---|
anu_public |
1 request a minute | 2 min | The window is a minute, and probing is free |
anu_quantum |
100 a month, free tier | 10 days | A probe is 1% of the month; ten days is three |
random_org |
1,000 a day | 1 hour | 24 of 1,000, to recover the same day |
The ten days for anu_quantum looks extreme until you do the arithmetic. The free tier is 100 requests a month, so every probe that only rediscovers an exhausted quota costs 1% of it. An hourly cooldown would spend seven hundred requests a month finding out it has none. Lower it hard on a paid plan, where a probe costs a fifth of a cent and recovering quickly is worth more than the request.
It is shared, and it fails open
The state lives in your application's default cache, so one worker learning that the quota is gone spares every other worker from finding out too.
And a cache that is down must not make randomness unavailable, or a site stops dealing cards because memcached is restarting. A cooldown that cannot be read is treated as no cooldown: the source is asked, and the worst case is the wasted request you were trying to avoid.