Handle API rate limits with exponential backoff and retry logic

This skill implements production-grade rate limiting, exponential backoff, and retry handling for external API calls, so a client respects upstream quotas instead of causing cascading failures. It classifies every response first: 2xx succeeds, 400/401/403/404 are terminal client errors that should never be retried, and 408/429/5xx are retryable with backoff. A getRetryDelay function checks upstream hints in priority order, the Retry-After header (seconds or HTTP-date format), then provider-specific reset headers such as GitHub's epoch-seconds x-ratelimit-reset, before falling back to capped exponential backoff with full jitter. A fetchWithRetry loop only retries requests it can establish are replay-safe (GET/HEAD/OPTIONS/PUT/DELETE, or a caller-confirmed idempotent write), enforces a maximum elapsed-time deadline across all attempts, and cancels the response body before waiting to release the connection. A TokenBucket client-side rate limiter, with configurable max tokens and refill rate, proactively throttles outgoing requests before they ever hit the upstream limit.

Use it when calling external APIs that enforce rate limits (OpenAI, Stripe, GitHub, and similar), when handling 429s or 5xx errors gracefully, when a client must respect Retry-After headers, or when fanning out to multiple API providers. Do not retry 4xx client errors other than 408/429 - those need the request fixed, not resent - and do not retry a non-idempotent write (a POST with side effects) unless the provider documents an idempotency mechanism and the same stable key is reused on every attempt.

Ships working TypeScript (getRetryDelay, fetchWithRetry, TokenBucket) and a Python equivalent (fetch_with_retry using httpx, parsing retry-after or falling back to 2 ** attempt + random jitter capped at 60s):

const limiter = new TokenBucket(60, 1);

async function rateLimitedFetch(url: string, options: RequestInit) {
  await limiter.acquire();
  return fetchWithRetry(url, options);
}

A worked example wires an idempotent GitHub GET through fetchWithRetry with 3 max retries, while a POST example explicitly notes to leave retryNonIdempotent false unless idempotency is documented and a stable key is reused. Best practices called out explicitly: always respect Retry-After, add jitter to avoid a thundering herd when multiple clients retry at once, log every retry with status, delay, and attempt number, cap total timeout so nothing hangs indefinitely, rate-limit proactively rather than only reacting to 429s, and never ignore per-endpoint quotas since some APIs vary limits by route.

Framework-agnostic at the fetch/httpx level, and explicitly notes its TokenBucket is only approximate for distributed systems - multi-instance deployments need a shared-store limiter such as Redis-backed rate limiting, pointing to a companion upstash-ratelimit skill or any shared-store limiter. It also names two related skills: @poka-yoke for mistake-proofing requests so invalid ones never reach the retry path, and @circuit-breaker for when to stop retrying entirely and fail fast.

Developers integrating with rate-limited third-party APIs who need concrete, copy-pasteable retry and backoff logic instead of reinventing it per integration, and who want the common pitfalls, such as retrying too aggressively during an outage, thundering herd, an HTTP-date Retry-After value, or a client-side limiter that ignores in-flight concurrent requests, already accounted for.