Retry-After, Backoff, and the Polite Agent Loop

Every public API rate limits eventually. The difference between a polite agent and a banned one is how it reads the limit signals.

How YJTOON rate limits

• 120 requests per minute per IP (hashed, so raw IPs are never stored)
• Every response carries X-RateLimit-Limit, X-RateLimit-Window, and X-RateLimit-Remaining
• Exceeding the limit returns 429 with a Retry-After header and a structured error body
• Repeated abuse escalates the cooldown (doubled wait) instead of a flat ban

The polite retry loop

1. Read X-RateLimit-Remaining. When it approaches zero, stop and wait until the window resets.
2. On 429, sleep Retry-After seconds plus a small random jitter. Exact retries synchronize badly when many agents share an IP.
3. Cap retries (3 is plenty for a reference API) and degrade gracefully: use the static file fallback instead of hammering the origin.
4. Cache aggressively. Reference data changes rarely; one fetch per session is usually enough.

Why escalating cooldowns are fair

A fixed ban punishes one burst. An escalating cooldown gives a misconfigured client time to correct itself while still stopping abuse. Agents that respect the headers never see the escalation.