Handle API rate limits with exponential backoff and retry logic

This skill implements production-grade rate limiting, exponential backoff, and retry strategies for calling external APIs, so a client doesn't cause cascading failures or get throttled. It classifies failed responses - 2xx as success; 400/401/403/404 as terminal client errors that should not be retried; 408/429 as retryable rate-limit or timeout errors; 500/502/503/504 as retryable server errors - and parses upstream rate-limit hints before computing its own delay: Retry-After in either seconds or HTTP-date format, and provider-specific headers like GitHub's epoch-second x-ratelimit-reset, falling back to capped exponential backoff with full jitter when no hint is present. A retry loop only retries replay-safe methods (GET, HEAD, OPTIONS, PUT, DELETE, or a non-idempotent method explicitly marked safe), enforces a maximum elapsed-time budget, and releases the response body before waiting. A proactive client-side token-bucket limiter, with configurable capacity and refill rate, throttles outgoing requests before they ever hit the upstream limit.

Use it when calling external APIs that enforce rate limits (OpenAI, Stripe, GitHub, etc.), when handling 429 or 5xx responses that need graceful recovery, when a client must respect Retry-After headers, or when fanning out to multiple API providers - triggered by phrases like "handle rate limits," "add retry logic," "backoff strategy," or "don't get throttled." Its own limitations note it does not replace environment-specific validation, testing, or expert review; that the shown token bucket is only approximate for distributed systems and multi-instance deployments need a Redis-backed shared limiter instead; that some APIs use non-standard rate-limit headers requiring their own documentation; and that its elapsed-time cap bounds retry waits, not a single hung network call, which still needs an AbortSignal or client timeout.

Input is an HTTP request plus retry parameters (max retries, max elapsed time, whether non-idempotent methods may be retried).

// Usage: limit to 60 requests/minute
const limiter = new TokenBucket(60, 1);

Output is either the successful response or a thrown error naming the terminal status, an exhausted-retry count, or an exceeded retry deadline; every retry attempt is logged with its status code, computed delay, and attempt number. Reference implementations are given in both TypeScript (fetch-based) and Python (httpx-based).

Designed for any HTTP client - fetch and httpx are both shown explicitly - and any rate-limited provider, with GitHub called out by name for its epoch-second reset header. It composes with two related skills instead of duplicating their scope: a poka-yoke skill for mistake-proofing requests so invalid calls never reach the retry path, and a circuit-breaker skill for deciding when to stop retrying entirely and fail fast.

Developers integrating with rate-limited third-party APIs who need battle-tested retry, backoff, and proactive throttling logic - respecting Retry-After, adding jitter, capping total wait time, only retrying safe methods - instead of writing ad hoc retry loops that risk amplifying an outage.