Rate limits, retries, and exponential backoff

Three ways to see it

1. 1

   Rate limiting is the explicit cap an API sets on how many requests one caller can make in a given window. A typical limit is 60 requests per minute, or 1000 per hour, or 100 per second. The cap is announced in two ways. Quietly, through HTTP headers: X-RateLimit-Limit tells you the total budget, X-RateLimit-Remaining tells you what is left, X-RateLimit-Reset tells you when it refills. Loudly, through the 429 status code: too many requests, you have been throttled. The polite client watches the headers and never sees the 429. The lazy client sees nothing but 429.

2. 2

   Pakistani context. The State Bank's PRISM and RAAST gateways throttle by participant. NADRA's verification API is throttled per partner bank, typically a few hundred verifications per minute per branch. FBR's IRIS API limits taxpayer queries to a handful per minute per NTN. The Easypaisa merchant API caps transactions per merchant per second to keep the underlying SBP rails healthy. The limits are not punitive. They are how the country's payment and identity rails stay alive when ten million Pakistanis hit them at the same moment.

3. 3

   Exponential backoff is the disciplined way a client responds to a 429 or a 5xx error. Wait one second, retry. If it fails again, wait two seconds. Then four, then eight, then sixteen, capped at sixty. Why double each time? Because if you and ten thousand other clients all retry after the same one-second wait, you create a thundering herd that crashes the server again. Doubling spreads everyone out across an expanding window. Add jitter, a random offset of a few hundred milliseconds, and even the doubling pattern stops being synchronised. The single most professional pattern in API engineering is 'exponential backoff with full jitter, capped, and a hard maximum number of retries'.

The why-tree

Try this with Claude

AI-edge prompt to try with Claude or ChatGPT: 'Write Python code that calls a Pakistani API which limits to 60 requests per minute, processes a list of 10,000 NTNs, uses capped exponential backoff with full jitter, max 5 retries, and an idempotency key on every write. Comments in Urdu transliterated. Explain why each design choice matters.' Read the code line by line and challenge every assumption.