{ "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": { "downloadMode": "redirect", "downloadUrl": "/downloads/api-rate-limiting", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=api-rate-limiting", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "README.md", "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "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." ], "prompts": [ { "label": "New install", "body": "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." }, { "label": "Upgrade existing", "body": "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." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "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." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/api-rate-limiting", "agentPageUrl": "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" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "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." ], "prompts": [ { "label": "New install", "body": "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." }, { "label": "Upgrade existing", "body": "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." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Algorithms", "body": "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\n\nFixed window problem: A user sends the full limit at 11:59 and again at 12:01, doubling the effective rate. Sliding window fixes this." }, { "title": "Token Bucket", "body": "Bucket holds tokens up to capacity. Tokens refill at a fixed rate. Each request consumes one.\n\nclass TokenBucket:\n def __init__(self, capacity: int, refill_rate: float):\n self.capacity = capacity\n self.tokens = capacity\n self.refill_rate = refill_rate # tokens per second\n self.last_refill = time.monotonic()\n\n def allow(self) -> bool:\n now = time.monotonic()\n elapsed = now - self.last_refill\n self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)\n self.last_refill = now\n if self.tokens >= 1:\n self.tokens -= 1\n return True\n return False" }, { "title": "Sliding Window Counter", "body": "Hybrid of fixed window and sliding window log — weights the previous window's count by overlap percentage:\n\ndef sliding_window_allow(key: str, limit: int, window_sec: int) -> bool:\n now = time.time()\n current_window = int(now // window_sec)\n position_in_window = (now % window_sec) / window_sec\n\n prev_count = get_count(key, current_window - 1)\n curr_count = get_count(key, current_window)\n\n estimated = prev_count * (1 - position_in_window) + curr_count\n if estimated >= limit:\n return False\n increment_count(key, current_window)\n return True" }, { "title": "Implementation Options", "body": "ApproachScopeBest ForIn-memorySingle serverZero latency, no dependenciesRedis (INCR + EXPIRE)DistributedMulti-instance deploymentsAPI GatewayEdgeNo code, built-in dashboardsMiddlewarePer-serviceFine-grained per-user/endpoint control\n\nUse gateway-level limiting as outer defense + application-level for fine-grained control." }, { "title": "HTTP Headers", "body": "Always return rate limit info, even on successful requests:\n\nRateLimit-Limit: 1000\nRateLimit-Remaining: 742\nRateLimit-Reset: 1625097600\nRetry-After: 30\n\nHeaderWhen to IncludeRateLimit-LimitEvery responseRateLimit-RemainingEvery responseRateLimit-ResetEvery responseRetry-After429 responses only" }, { "title": "429 Response Body", "body": "{\n \"error\": {\n \"code\": \"rate_limit_exceeded\",\n \"message\": \"Rate limit exceeded. Maximum 1000 requests per hour.\",\n \"retry_after\": 30,\n \"limit\": 1000,\n \"reset_at\": \"2025-07-01T12:00:00Z\"\n }\n}\n\nNever return 500 or 503 for rate limiting — 429 is the correct status code." }, { "title": "Rate Limit Tiers", "body": "Apply limits at multiple granularities:\n\nScopeKeyExample 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\n\nTiered pricing:\n\nTierRate LimitBurstCostFree100 req/hr10$0Pro5,000 req/hr100$49/moEnterprise100,000 req/hr2,000Custom\n\nEvaluate from most specific to least specific: per-endpoint > per-user > per-IP." }, { "title": "Distributed Rate Limiting", "body": "Redis-based pattern for consistent limiting across instances:\n\ndef redis_rate_limit(redis, key: str, limit: int, window: int) -> bool:\n pipe = redis.pipeline()\n now = time.time()\n window_key = f\"rl:{key}:{int(now // window)}\"\n pipe.incr(window_key)\n pipe.expire(window_key, window * 2)\n results = pipe.execute()\n return results[0] <= limit\n\nAtomic Lua script (prevents race conditions):\n\nlocal key = KEYS[1]\nlocal limit = tonumber(ARGV[1])\nlocal window = tonumber(ARGV[2])\nlocal current = redis.call('INCR', key)\nif current == 1 then\n redis.call('EXPIRE', key, window)\nend\nreturn current <= limit and 1 or 0\n\nNever do separate GET then SET — the gap allows overcount." }, { "title": "API Gateway Configuration", "body": "NGINX:\n\nhttp {\n limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;\n server {\n location /api/ {\n limit_req zone=api burst=20 nodelay;\n limit_req_status 429;\n }\n }\n}\n\nKong:\n\nplugins:\n - name: rate-limiting\n config:\n minute: 60\n hour: 1000\n policy: redis\n redis_host: redis.internal" }, { "title": "Client-Side Handling", "body": "Clients must handle 429 gracefully:\n\nasync function fetchWithRetry(url: string, maxRetries = 3): Promise {\n for (let attempt = 0; attempt < maxRetries; attempt++) {\n const res = await fetch(url);\n if (res.status !== 429) return res;\n\n const retryAfter = res.headers.get('Retry-After');\n const delay = retryAfter\n ? parseInt(retryAfter, 10) * 1000\n : Math.min(1000 * 2 ** attempt, 30000);\n await new Promise(r => setTimeout(r, delay));\n }\n throw new Error('Rate limit exceeded after retries');\n}\n\nAlways respect Retry-After when present\nUse exponential backoff with jitter when absent\nImplement request queuing for batch operations" }, { "title": "Monitoring", "body": "Track these metrics:\n\nRate limit hit rate — % of requests returning 429 (alert if >5% sustained)\nNear-limit warnings — requests where remaining < 10% of limit\nTop offenders — keys/IPs hitting limits most frequently\nLimit headroom — how close normal traffic is to the ceiling\nFalse positives — legitimate users being rate limited" }, { "title": "Anti-Patterns", "body": "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" }, { "title": "NEVER Do", "body": "NEVER rate limit health check endpoints — monitoring systems will false-alarm\nNEVER use client-supplied identifiers as sole rate limit key — trivially spoofed\nNEVER return 200 OK when rate limiting — clients must know they were throttled\nNEVER set limits without measuring actual traffic first — you'll block legitimate users or set limits too high to matter\nNEVER share counters across unrelated tenants — noisy neighbor problem\nNEVER skip rate limiting on internal APIs — misbehaving internal services can take down shared infrastructure\nNEVER implement rate limiting without logging — you need visibility to tune limits and detect abuse" } ], "body": "Rate Limiting Patterns\nAlgorithms\nAlgorithm\tAccuracy\tBurst Handling\tBest For\nToken Bucket\tHigh\tAllows controlled bursts\tAPI rate limiting, traffic shaping\nLeaky Bucket\tHigh\tSmooths bursts entirely\tSteady-rate processing, queues\nFixed Window\tLow\tAllows edge bursts (2x)\tSimple use cases, prototyping\nSliding Window Log\tVery High\tPrecise control\tStrict compliance, billing-critical\nSliding Window Counter\tHigh\tGood approximation\tProduction APIs — best tradeoff\n\nFixed window problem: A user sends the full limit at 11:59 and again at 12:01, doubling the effective rate. Sliding window fixes this.\n\nToken Bucket\n\nBucket holds tokens up to capacity. Tokens refill at a fixed rate. Each request consumes one.\n\nclass TokenBucket:\n def __init__(self, capacity: int, refill_rate: float):\n self.capacity = capacity\n self.tokens = capacity\n self.refill_rate = refill_rate # tokens per second\n self.last_refill = time.monotonic()\n\n def allow(self) -> bool:\n now = time.monotonic()\n elapsed = now - self.last_refill\n self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)\n self.last_refill = now\n if self.tokens >= 1:\n self.tokens -= 1\n return True\n return False\n\nSliding Window Counter\n\nHybrid of fixed window and sliding window log — weights the previous window's count by overlap percentage:\n\ndef sliding_window_allow(key: str, limit: int, window_sec: int) -> bool:\n now = time.time()\n current_window = int(now // window_sec)\n position_in_window = (now % window_sec) / window_sec\n\n prev_count = get_count(key, current_window - 1)\n curr_count = get_count(key, current_window)\n\n estimated = prev_count * (1 - position_in_window) + curr_count\n if estimated >= limit:\n return False\n increment_count(key, current_window)\n return True\n\nImplementation Options\nApproach\tScope\tBest For\nIn-memory\tSingle server\tZero latency, no dependencies\nRedis (INCR + EXPIRE)\tDistributed\tMulti-instance deployments\nAPI Gateway\tEdge\tNo code, built-in dashboards\nMiddleware\tPer-service\tFine-grained per-user/endpoint control\n\nUse gateway-level limiting as outer defense + application-level for fine-grained control.\n\nHTTP Headers\n\nAlways return rate limit info, even on successful requests:\n\nRateLimit-Limit: 1000\nRateLimit-Remaining: 742\nRateLimit-Reset: 1625097600\nRetry-After: 30\n\nHeader\tWhen to Include\nRateLimit-Limit\tEvery response\nRateLimit-Remaining\tEvery response\nRateLimit-Reset\tEvery response\nRetry-After\t429 responses only\n429 Response Body\n{\n \"error\": {\n \"code\": \"rate_limit_exceeded\",\n \"message\": \"Rate limit exceeded. Maximum 1000 requests per hour.\",\n \"retry_after\": 30,\n \"limit\": 1000,\n \"reset_at\": \"2025-07-01T12:00:00Z\"\n }\n}\n\n\nNever return 500 or 503 for rate limiting — 429 is the correct status code.\n\nRate Limit Tiers\n\nApply limits at multiple granularities:\n\nScope\tKey\tExample Limit\tPurpose\nPer-IP\tClient IP\t100 req/min\tAbuse prevention\nPer-User\tUser ID\t1000 req/hr\tFair usage\nPer-API-Key\tAPI key\t5000 req/hr\tService-to-service\nPer-Endpoint\tRoute + key\t60 req/min on /search\tProtect expensive ops\n\nTiered pricing:\n\nTier\tRate Limit\tBurst\tCost\nFree\t100 req/hr\t10\t$0\nPro\t5,000 req/hr\t100\t$49/mo\nEnterprise\t100,000 req/hr\t2,000\tCustom\n\nEvaluate from most specific to least specific: per-endpoint > per-user > per-IP.\n\nDistributed Rate Limiting\n\nRedis-based pattern for consistent limiting across instances:\n\ndef redis_rate_limit(redis, key: str, limit: int, window: int) -> bool:\n pipe = redis.pipeline()\n now = time.time()\n window_key = f\"rl:{key}:{int(now // window)}\"\n pipe.incr(window_key)\n pipe.expire(window_key, window * 2)\n results = pipe.execute()\n return results[0] <= limit\n\n\nAtomic Lua script (prevents race conditions):\n\nlocal key = KEYS[1]\nlocal limit = tonumber(ARGV[1])\nlocal window = tonumber(ARGV[2])\nlocal current = redis.call('INCR', key)\nif current == 1 then\n redis.call('EXPIRE', key, window)\nend\nreturn current <= limit and 1 or 0\n\n\nNever do separate GET then SET — the gap allows overcount.\n\nAPI Gateway Configuration\n\nNGINX:\n\nhttp {\n limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;\n server {\n location /api/ {\n limit_req zone=api burst=20 nodelay;\n limit_req_status 429;\n }\n }\n}\n\n\nKong:\n\nplugins:\n - name: rate-limiting\n config:\n minute: 60\n hour: 1000\n policy: redis\n redis_host: redis.internal\n\nClient-Side Handling\n\nClients must handle 429 gracefully:\n\nasync function fetchWithRetry(url: string, maxRetries = 3): Promise {\n for (let attempt = 0; attempt < maxRetries; attempt++) {\n const res = await fetch(url);\n if (res.status !== 429) return res;\n\n const retryAfter = res.headers.get('Retry-After');\n const delay = retryAfter\n ? parseInt(retryAfter, 10) * 1000\n : Math.min(1000 * 2 ** attempt, 30000);\n await new Promise(r => setTimeout(r, delay));\n }\n throw new Error('Rate limit exceeded after retries');\n}\n\nAlways respect Retry-After when present\nUse exponential backoff with jitter when absent\nImplement request queuing for batch operations\nMonitoring\n\nTrack these metrics:\n\nRate limit hit rate — % of requests returning 429 (alert if >5% sustained)\nNear-limit warnings — requests where remaining < 10% of limit\nTop offenders — keys/IPs hitting limits most frequently\nLimit headroom — how close normal traffic is to the ceiling\nFalse positives — legitimate users being rate limited\nAnti-Patterns\nAnti-Pattern\tFix\nApplication-only limiting\tAlways combine with infrastructure-level limits\nNo retry guidance\tAlways include Retry-After header on 429\nInconsistent limits\tSame endpoint, same limits across services\nNo burst allowance\tAllow controlled bursts for legitimate traffic\nSilent dropping\tAlways return 429 so clients can distinguish from errors\nGlobal single counter\tPer-endpoint counters to protect expensive operations\nHard-coded limits\tUse configuration, not code constants\nNEVER Do\nNEVER rate limit health check endpoints — monitoring systems will false-alarm\nNEVER use client-supplied identifiers as sole rate limit key — trivially spoofed\nNEVER return 200 OK when rate limiting — clients must know they were throttled\nNEVER set limits without measuring actual traffic first — you'll block legitimate users or set limits too high to matter\nNEVER share counters across unrelated tenants — noisy neighbor problem\nNEVER skip rate limiting on internal APIs — misbehaving internal services can take down shared infrastructure\nNEVER implement rate limiting without logging — you need visibility to tune limits and detect abuse" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/wpank/api-rate-limiting", "publisherUrl": "https://clawhub.ai/wpank/api-rate-limiting", "owner": "wpank", "version": "1.0.0", "license": null, "verificationStatus": "Indexed source record" }, "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" } }