api-ratelimit-helper

Name: api-ratelimit-helper
Author: LambdaTest

335stars67forks

How to install api-ratelimit-helper?

lambdatest/agent-skills/api-ratelimit-helper

$npx -y skills add LambdaTest/agent-skills --skill api-ratelimit-helper

Installs into the current project.

Summary

Designs rate limiting strategies, quota systems, throttling policies, retry logic, and backoff patterns for APIs. Use whenever the user asks about rate limiting, throttling, quotas, "too many requests", 429 responses, "how do I limit my API", "retry strategy", "exponential backof

Files · 1

View on GitHub

SKILL.md

1	# API Rate Limiting Skill
2
3	Design complete rate limiting, quota, and retry systems for any API.
4
5	---
6
7	## Rate Limiting Algorithms
8
9	\| Algorithm \| Best For \| Trade-offs \|
10	\|-----------\|----------\|------------\|
11	\| Token bucket \| Bursty traffic with sustained avg \| Allows bursts; slightly complex \|
12	\| Leaky bucket \| Strict rate enforcement \| Smooths bursts; can feel slow \|
13	\| Fixed window \| Simple counting \| Boundary spike problem \|
14	\| Sliding window log \| Precise limiting \| Memory-intensive \|
15	\| Sliding window counter \| Balance of precision/memory \| Best for most APIs \|
16
17	Recommendation: Use sliding window counter for API endpoints, token bucket for streaming/upload endpoints.
18
19	---
20
21	## Response Headers (RFC standard)
22
23	```http
24	X-RateLimit-Limit: 100
25	X-RateLimit-Remaining: 42
26	X-RateLimit-Reset: 1700000060
27	X-RateLimit-Policy: 100;w=60;comment="per minute"
28	Retry-After: 18
29	```
30
31	### 429 Response Body
32	```json
33	{
34	"error": "rate_limit_exceeded",
35	"message": "Too many requests. You have exceeded 100 requests per minute.",
36	"retry_after_seconds": 18,
37	"limit": 100,
38	"window": "60s",
39	"reset_at": "2024-01-01T00:01:00Z"
40	}
41	```
42
43	---
44
45	## Tiered Quota Design
46
47	\| Tier \| Requests/min \| Requests/day \| Burst \| Concurrent \|
48	\|------\|-------------\|--------------\|-------\|------------\|
49	\| Free \| 10 \| 1,000 \| 20 \| 2 \|
50	\| Starter \| 100 \| 50,000 \| 200 \| 10 \|
51	\| Pro \| 1,000 \| 500,000 \| 2,000 \| 50 \|
52	\| Enterprise \| Custom \| Unlimited \| Custom \| Custom \|
53
54	### Quota Endpoints
55	```
56	GET /api/v1/account/quota — current usage vs limits
57	GET /api/v1/account/quota/history — usage over time
58	```
59
60	Response:
61	```json
62	{
63	"plan": "pro",
64	"period": "2024-01",
65	"limits": { "requests_per_minute": 1000, "requests_per_day": 500000 },
66	"usage": { "requests_today": 12345, "requests_this_minute": 234 },
67	"resets_at": "2024-02-01T00:00:00Z"
68	}
69	```
70
71	---
72
73	## Retry Logic (client-side)
74
75	### Exponential backoff with jitter
76	```python
77	import random, time
78
79	def retry_with_backoff(fn, max_retries=5, base_delay=1.0, max_delay=60.0):
80	for attempt in range(max_retries):
81	try:
82	return fn()
83	except RateLimitError as e:
84	if attempt == max_retries - 1:
85	raise
86	# Use Retry-After header if present, else exponential backoff
87	delay = min(
88	e.retry_after or (base_delay * (2 ** attempt)),
89	max_delay
90	)
91	# Add jitter to prevent thundering herd
92	delay += random.uniform(0, delay * 0.1)
93	time.sleep(delay)
94	```
95
96	### Retryable vs Non-retryable status codes
97	\| Status \| Retry? \| Strategy \|
98	\|--------\|--------\|----------\|
99	\| 429 \| Yes \| Respect `Retry-After` header \|
100	\| 500 \| Yes \| Exponential backoff \|
101	\| 502/503 \| Yes \| Exponential backoff \|
102	\| 504 \| Yes \| Exponential backoff \|
103	\| 400 \| No \| Fix request \|
104	\| 401 \| No \| Refresh token, then retry once \|
105	\| 403 \| No \| Fix permissions \|
106	\| 404 \| No \| Fix URL \|
107	\| 422 \| No \| Fix payload \|
108
109	---
110
111	## Circuit Breaker Pattern
112
113	```
114	States: CLOSED → OPEN → HALF-OPEN → CLOSED
115
116	CLOSED: normal operation
117	- Track failure rate in rolling window
118	- If failure rate > threshold (e.g. 50% in 10s): → OPEN
119
120	OPEN: reject all requests immediately (fail-fast)
121	- Return 503 without calling downstream
122	- After cooldown period (e.g. 30s): → HALF-OPEN
123
124	HALF-OPEN: allow limited traffic through
125	- If first N requests succeed: → CLOSED
126	- If any fail: → OPEN again
127	```
128
129	---
130
131	## Idempotency Keys
132
133	For state-changing requests that may be retried:
134	```http
135	POST /api/v1/payments
136	Idempotency-Key: uuid-v4-client-generated
137
138	Response includes:
139	Idempotency-Key: uuid-v4-client-generated
140	X-Idempotent-Replayed: true (if this is a duplicate)
141	```
142
143	Store: idempotency key → response, expire after 24h. Return cached response for duplicate keys.
144
145	---
146
147	## After Completing the API Ratelimit Output
148
149	Once the API ratelimit output is delivered, ask the user:
150
151	"Would you like me to generate API documentation for this design? (yes/no)"
152
153	If the user says yes:
154	- Check if the API Documentation skill is available in the installed skills list
155	- If the skill is available:
156	- Read and follow the instructions in the API Documentation skill

People who liked this also viewed

6 picks

Type

api-ratelimit-helper

335stars67forks

View on GitHub

How to install api-ratelimit-helper?

lambdatest/agent-skills/api-ratelimit-helper

$npx -y skills add LambdaTest/agent-skills --skill api-ratelimit-helper

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Rate Limiting Skill
2
3	Design complete rate limiting, quota, and retry systems for any API.
4
5	---
6
7	## Rate Limiting Algorithms
8
9	\| Algorithm \| Best For \| Trade-offs \|
10	\|-----------\|----------\|------------\|
11	\| Token bucket \| Bursty traffic with sustained avg \| Allows bursts; slightly complex \|
12	\| Leaky bucket \| Strict rate enforcement \| Smooths bursts; can feel slow \|
13	\| Fixed window \| Simple counting \| Boundary spike problem \|
14	\| Sliding window log \| Precise limiting \| Memory-intensive \|
15	\| Sliding window counter \| Balance of precision/memory \| Best for most APIs \|
16
17	Recommendation: Use sliding window counter for API endpoints, token bucket for streaming/upload endpoints.
18
19	---
20
21	## Response Headers (RFC standard)
22
23	```http
24	X-RateLimit-Limit: 100
25	X-RateLimit-Remaining: 42
26	X-RateLimit-Reset: 1700000060
27	X-RateLimit-Policy: 100;w=60;comment="per minute"
28	Retry-After: 18
29	```
30
31	### 429 Response Body
32	```json
33	{
34	"error": "rate_limit_exceeded",
35	"message": "Too many requests. You have exceeded 100 requests per minute.",
36	"retry_after_seconds": 18,
37	"limit": 100,
38	"window": "60s",
39	"reset_at": "2024-01-01T00:01:00Z"
40	}
41	```
42
43	---
44
45	## Tiered Quota Design
46
47	\| Tier \| Requests/min \| Requests/day \| Burst \| Concurrent \|
48	\|------\|-------------\|--------------\|-------\|------------\|
49	\| Free \| 10 \| 1,000 \| 20 \| 2 \|
50	\| Starter \| 100 \| 50,000 \| 200 \| 10 \|
51	\| Pro \| 1,000 \| 500,000 \| 2,000 \| 50 \|
52	\| Enterprise \| Custom \| Unlimited \| Custom \| Custom \|
53
54	### Quota Endpoints
55	```
56	GET /api/v1/account/quota — current usage vs limits
57	GET /api/v1/account/quota/history — usage over time
58	```
59
60	Response:
61	```json
62	{
63	"plan": "pro",
64	"period": "2024-01",
65	"limits": { "requests_per_minute": 1000, "requests_per_day": 500000 },
66	"usage": { "requests_today": 12345, "requests_this_minute": 234 },
67	"resets_at": "2024-02-01T00:00:00Z"
68	}
69	```
70
71	---
72
73	## Retry Logic (client-side)
74
75	### Exponential backoff with jitter
76	```python
77	import random, time
78
79	def retry_with_backoff(fn, max_retries=5, base_delay=1.0, max_delay=60.0):
80	for attempt in range(max_retries):
81	try:
82	return fn()
83	except RateLimitError as e:
84	if attempt == max_retries - 1:
85	raise
86	# Use Retry-After header if present, else exponential backoff
87	delay = min(
88	e.retry_after or (base_delay * (2 ** attempt)),
89	max_delay
90	)
91	# Add jitter to prevent thundering herd
92	delay += random.uniform(0, delay * 0.1)
93	time.sleep(delay)
94	```
95
96	### Retryable vs Non-retryable status codes
97	\| Status \| Retry? \| Strategy \|
98	\|--------\|--------\|----------\|
99	\| 429 \| Yes \| Respect `Retry-After` header \|
100	\| 500 \| Yes \| Exponential backoff \|
101	\| 502/503 \| Yes \| Exponential backoff \|
102	\| 504 \| Yes \| Exponential backoff \|
103	\| 400 \| No \| Fix request \|
104	\| 401 \| No \| Refresh token, then retry once \|
105	\| 403 \| No \| Fix permissions \|
106	\| 404 \| No \| Fix URL \|
107	\| 422 \| No \| Fix payload \|
108
109	---
110
111	## Circuit Breaker Pattern
112
113	```
114	States: CLOSED → OPEN → HALF-OPEN → CLOSED
115
116	CLOSED: normal operation
117	- Track failure rate in rolling window
118	- If failure rate > threshold (e.g. 50% in 10s): → OPEN
119
120	OPEN: reject all requests immediately (fail-fast)
121	- Return 503 without calling downstream
122	- After cooldown period (e.g. 30s): → HALF-OPEN
123
124	HALF-OPEN: allow limited traffic through
125	- If first N requests succeed: → CLOSED
126	- If any fail: → OPEN again
127	```
128
129	---
130
131	## Idempotency Keys
132
133	For state-changing requests that may be retried:
134	```http
135	POST /api/v1/payments
136	Idempotency-Key: uuid-v4-client-generated
137
138	Response includes:
139	Idempotency-Key: uuid-v4-client-generated
140	X-Idempotent-Replayed: true (if this is a duplicate)
141	```
142
143	Store: idempotency key → response, expire after 24h. Return cached response for duplicate keys.
144
145	---
146
147	## After Completing the API Ratelimit Output
148
149	Once the API ratelimit output is delivered, ask the user:
150
151	"Would you like me to generate API documentation for this design? (yes/no)"
152
153	If the user says yes:
154	- Check if the API Documentation skill is available in the installed skills list
155	- If the skill is available:
156	- Read and follow the instructions in the API Documentation skill

People who liked this also viewed

6 picks

Type