# API Rate Limiting

> Design API rate limiting with token bucket/sliding/fixed windows, RateLimit headers, 429 vs 503, and per-key/endpoint scopes. Use when protecting APIs from abuse or implementing quotas.

- Skill: `deangrant/api-rate-limiting` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/api-rate-limiting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/api-rate-limiting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/api-rate-limiting

---


# API Rate Limiting

Use this skill when applying **quotas and abuse protection**.

---

## 1. Algorithms

Token bucket (smooth bursts) is a common default; fixed/sliding windows are
alternatives. Document the chosen model.

---

## 2. Scoping

Limit per identity/IP **and** per-tenant; tighter limits on expensive routes
(export, search, reset). Cap page size / payload size too.

---

## 3. Responses

| Case | Status |
| ---- | ------ |
| Client over quota | **429** + `Retry-After` + `RateLimit-*` |
| System overload | **503** + `Retry-After` |

---

## 4. Quick checklist

- [ ] Algorithm + scopes documented.
- [ ] Per-key and per-endpoint limits where needed.
- [ ] 429 vs 503 distinguished.
- [ ] RateLimit-* and Retry-After emitted.
- [ ] Clients honor Retry-After.

See [reference.md](reference.md) and [examples.md](examples.md).