Understanding Rate-Limit Response Headers (and the 429 Body)

Rate-limit headers are the difference between a polite API and a hostile one. Here is the small set YJTOON returns, and exactly what to do with each.

Headers on every response

• X-RateLimit-Limit: the per-window ceiling.
• X-RateLimit-Remaining: how many requests are left in the current window.
• X-RateLimit-Reset: epoch seconds when the window resets.

Headers on 429

• Retry-After: seconds to wait before retrying. Honor it.
• X-RateLimit-Window: human-readable window size ("1m", "1h").

The 429 body

{\n  "error": "rate_limited",\n  "retry_after_seconds": 23,\n  "request_id": "req_01HXY..." \n}\n

How to use them

On every response, look at X-RateLimit-Remaining. If it is below a threshold you set (we use 10%), start backing off. On 429, sleep for Retry-After and retry once. If you 429 twice in a row, surface the failure to the caller.

What not to do

Do not parse the body to extract the sleep time when the header is also there. Headers are stable; bodies can change.