api-rate-limiting-helper

Files (1)

• SKILL.md

SKILL.md (first lines)

# API Rate Limiting Skill

Design complete rate limiting, quota, and retry systems for any API.

---

## Rate Limiting Algorithms

| Algorithm | Best For | Trade-offs |
|-----------|----------|------------|
| **Token bucket** | Bursty traffic with sustained avg | Allows bursts; slightly complex |
| **Leaky bucket** | Strict rate enforcement | Smooths bursts; can feel slow |
| **Fixed window** | Simple counting | Boundary spike problem |
| **Sliding window log** | Precise limiting | Memory-intensive |
| **Sliding window counter** | Balance of precision/memory | Best for most APIs |

**Recommendation**: Use **sliding window counter** for API endpoints, **token bucket** for streaming/upload endpoints.

---

## Response Headers (RFC standard)

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1700000060
X-RateLimit-Policy: 100;w=60;comment="per minute"
Retry-After: 18
```

### 429 Response Body
```json
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. You have exceeded 100 requests per minute.",
  "retry_after_seconds": 18,
  "limit": 100,
  "window": "60s",
  "reset_at": "2024-01-01T00:01:00Z"
}
```

---

## Tiered Quota Design

| Tier | Requests/min | Requests/day | Burst | Concurrent |
|------|-------------|--------------|-------|------------|
| Free | 10 | 1,000 | 20 | 2 |
| Starter | 100 | 50,000 | 200 | 10 |
| Pro | 1,000 | 500,000 | 2,000 | 50 |
| Enterprise | Custom | Unlimited | Custom | Custom |

### Quota Endpoints
```
GET  /api/v1/account/quota         — current usage vs limits
GET  /api/v1/account/quota/history — usage over time
```

Response:
```json
{
  "plan": "pro",
  "period": "2024-01",
  "limits": { "requests_per_minute": 1000, "requests_per_day": 500000 },
  "usage": { "requests_today": 12345, "requests_this_minute": 234 },
  "resets_at": "2024-02-01T00:00:00Z"
}
```

---

## Retry Logic (client-side)

### Exponential backoff with jitter
```python
import random, time

def retry_with_backoff(fn, max_retries=5, base_delay=1.0, max_delay=60.0):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Use Retry-After header if present, else exponential backoff
            delay = min(
                e.retry_after or (base_delay * (2 ** attempt)),
                max_delay
            )
            # Add jitter to prevent thundering herd
            delay += random.uniform(0, delay * 0.1)
            time.sleep(delay)
```

### Retryable vs Non-retryable status codes
| Status | Retry? | Strategy |
|--------|--------|----------|
| 429 | Yes | Respect `Retry-After` header |
| 500 | Yes | Exponential backoff |
| 502/503 | Yes | Exponential backoff |
| 504 | Yes | Exponential backoff |
| 400 | No | Fix request |
| 401 | No | Refresh token, then retry once |
| 403 | No | Fix permissions |
| 404 | No | Fix URL |
| 422 | No | Fix payload |

---

## Circuit Breaker Pattern

```
States: CLOSED → OPEN → HALF-OPEN → CLOSED

CLOSED: normal operation
  - Track failure rate in rolling window
  - If failure rate > threshold (e.g. 50% in 10s): → OPEN

From LambdaTest/agent-skills, MIT.

More from LambdaTest/agent-skills