Handling a 429
Read Retry-After, it is not decorative
Both 429s carry it, and the two values mean very different things:
| Cause | Retry-After |
What to do |
|---|---|---|
| Per-minute cap | 60 |
pause the sender, resume after |
| Monthly allowance | seconds to the next UTC midnight | stop; waiting is not a strategy |
The second is often several hours. A retry loop that ignores the header and backs off exponentially will spend the rest of the day failing, and will look from our side like a client hammering a limit it has been told about.
The shape that works
on 429:
wait = Retry-After if present, else exponential with jitter
if wait > your tolerance: stop and alert a human
else: sleep, then retry the SAME request
Retry the same request, with the same Idempotency-Key. A fresh key on
retry is a new send, and if the original was accepted after all you have sent
twice. The key is what makes the retry safe. See
Idempotency.
Three that make it worse
Retrying immediately. The cap is a rolling 60-second window, so an
immediate retry is another 429 and another entry in the count that
determines when you recover.
Spreading across keys. Caps are per workspace. A second key buys nothing, and the pattern reads as evasion.
Treating a throttle as a rate cap. If your cap was lowered because of
your bounce rate, backing off and retrying forever never recovers it. Fix the
list. GET /v1/reputation tells you which
situation you are in, and it is the first thing to check when a 429 appears
on traffic that used to be fine.
Pace instead of colliding
The better pattern is not to hit the cap at all:
remaining = rate_cap_per_min - messages_sent_last_60s
Both from GET /v1/usage. Because that count includes
everything on the workspace, not only your process, it is the only basis that
holds when a colleague is also sending.