# Send API Rate Limiting to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "api-rate-limiting", "name": "API Rate Limiting", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/wpank/api-rate-limiting", "canonicalUrl": "https://clawhub.ai/wpank/api-rate-limiting", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/api-rate-limiting", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-rate-limiting", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "README.md", "SKILL.md" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "api-rate-limiting", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-29T05:56:15.538Z", "expiresAt": "2026-05-06T05:56:15.538Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-rate-limiting", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-rate-limiting", "contentDisposition": "attachment; filename=\"api-rate-limiting-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "api-rate-limiting" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/api-rate-limiting" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/api-rate-limiting", "downloadUrl": "https://openagent3.xyz/downloads/api-rate-limiting", "agentUrl": "https://openagent3.xyz/skills/api-rate-limiting/agent", "manifestUrl": "https://openagent3.xyz/skills/api-rate-limiting/agent.json", "briefUrl": "https://openagent3.xyz/skills/api-rate-limiting/agent.md" } } ``` ## Documentation ### Algorithms AlgorithmAccuracyBurst HandlingBest ForToken BucketHighAllows controlled burstsAPI rate limiting, traffic shapingLeaky BucketHighSmooths bursts entirelySteady-rate processing, queuesFixed WindowLowAllows edge bursts (2x)Simple use cases, prototypingSliding Window LogVery HighPrecise controlStrict compliance, billing-criticalSliding Window CounterHighGood approximationProduction APIs — best tradeoff Fixed window problem: A user sends the full limit at 11:59 and again at 12:01, doubling the effective rate. Sliding window fixes this. ### Token Bucket Bucket holds tokens up to capacity. Tokens refill at a fixed rate. Each request consumes one. class TokenBucket: def __init__(self, capacity: int, refill_rate: float): self.capacity = capacity self.tokens = capacity self.refill_rate = refill_rate # tokens per second self.last_refill = time.monotonic() def allow(self) -> bool: now = time.monotonic() elapsed = now - self.last_refill self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate) self.last_refill = now if self.tokens >= 1: self.tokens -= 1 return True return False ### Sliding Window Counter Hybrid of fixed window and sliding window log — weights the previous window's count by overlap percentage: def sliding_window_allow(key: str, limit: int, window_sec: int) -> bool: now = time.time() current_window = int(now // window_sec) position_in_window = (now % window_sec) / window_sec prev_count = get_count(key, current_window - 1) curr_count = get_count(key, current_window) estimated = prev_count * (1 - position_in_window) + curr_count if estimated >= limit: return False increment_count(key, current_window) return True ### Implementation Options ApproachScopeBest ForIn-memorySingle serverZero latency, no dependenciesRedis (INCR + EXPIRE)DistributedMulti-instance deploymentsAPI GatewayEdgeNo code, built-in dashboardsMiddlewarePer-serviceFine-grained per-user/endpoint control Use gateway-level limiting as outer defense + application-level for fine-grained control. ### HTTP Headers Always return rate limit info, even on successful requests: RateLimit-Limit: 1000 RateLimit-Remaining: 742 RateLimit-Reset: 1625097600 Retry-After: 30 HeaderWhen to IncludeRateLimit-LimitEvery responseRateLimit-RemainingEvery responseRateLimit-ResetEvery responseRetry-After429 responses only ### 429 Response Body { "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Maximum 1000 requests per hour.", "retry_after": 30, "limit": 1000, "reset_at": "2025-07-01T12:00:00Z" } } Never return 500 or 503 for rate limiting — 429 is the correct status code. ### Rate Limit Tiers Apply limits at multiple granularities: ScopeKeyExample LimitPurposePer-IPClient IP100 req/minAbuse preventionPer-UserUser ID1000 req/hrFair usagePer-API-KeyAPI key5000 req/hrService-to-servicePer-EndpointRoute + key60 req/min on /searchProtect expensive ops Tiered pricing: TierRate LimitBurstCostFree100 req/hr10$0Pro5,000 req/hr100$49/moEnterprise100,000 req/hr2,000Custom Evaluate from most specific to least specific: per-endpoint > per-user > per-IP. ### Distributed Rate Limiting Redis-based pattern for consistent limiting across instances: def redis_rate_limit(redis, key: str, limit: int, window: int) -> bool: pipe = redis.pipeline() now = time.time() window_key = f"rl:{key}:{int(now // window)}" pipe.incr(window_key) pipe.expire(window_key, window * 2) results = pipe.execute() return results[0] <= limit Atomic Lua script (prevents race conditions): local key = KEYS[1] local limit = tonumber(ARGV[1]) local window = tonumber(ARGV[2]) local current = redis.call('INCR', key) if current == 1 then redis.call('EXPIRE', key, window) end return current <= limit and 1 or 0 Never do separate GET then SET — the gap allows overcount. ### API Gateway Configuration NGINX: http { limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s; server { location /api/ { limit_req zone=api burst=20 nodelay; limit_req_status 429; } } } Kong: plugins: - name: rate-limiting config: minute: 60 hour: 1000 policy: redis redis_host: redis.internal ### Client-Side Handling Clients must handle 429 gracefully: async function fetchWithRetry(url: string, maxRetries = 3): Promise { for (let attempt = 0; attempt < maxRetries; attempt++) { const res = await fetch(url); if (res.status !== 429) return res; const retryAfter = res.headers.get('Retry-After'); const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.min(1000 * 2 ** attempt, 30000); await new Promise(r => setTimeout(r, delay)); } throw new Error('Rate limit exceeded after retries'); } Always respect Retry-After when present Use exponential backoff with jitter when absent Implement request queuing for batch operations ### Monitoring Track these metrics: Rate limit hit rate — % of requests returning 429 (alert if >5% sustained) Near-limit warnings — requests where remaining < 10% of limit Top offenders — keys/IPs hitting limits most frequently Limit headroom — how close normal traffic is to the ceiling False positives — legitimate users being rate limited ### Anti-Patterns Anti-PatternFixApplication-only limitingAlways combine with infrastructure-level limitsNo retry guidanceAlways include Retry-After header on 429Inconsistent limitsSame endpoint, same limits across servicesNo burst allowanceAllow controlled bursts for legitimate trafficSilent droppingAlways return 429 so clients can distinguish from errorsGlobal single counterPer-endpoint counters to protect expensive operationsHard-coded limitsUse configuration, not code constants ### NEVER Do NEVER rate limit health check endpoints — monitoring systems will false-alarm NEVER use client-supplied identifiers as sole rate limit key — trivially spoofed NEVER return 200 OK when rate limiting — clients must know they were throttled NEVER set limits without measuring actual traffic first — you'll block legitimate users or set limits too high to matter NEVER share counters across unrelated tenants — noisy neighbor problem NEVER skip rate limiting on internal APIs — misbehaving internal services can take down shared infrastructure NEVER implement rate limiting without logging — you need visibility to tune limits and detect abuse ## Trust - Source: tencent - Verification: Indexed source record - Publisher: wpank - Version: 1.0.0 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-04-29T05:56:15.538Z - Expires at: 2026-05-06T05:56:15.538Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/api-rate-limiting) - [Send to Agent page](https://openagent3.xyz/skills/api-rate-limiting/agent) - [JSON manifest](https://openagent3.xyz/skills/api-rate-limiting/agent.json) - [Markdown brief](https://openagent3.xyz/skills/api-rate-limiting/agent.md) - [Download page](https://openagent3.xyz/downloads/api-rate-limiting)