diff --git a/docs/API.md b/docs/API.md
index 900168f..c4ee4c8 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -64,7 +64,24 @@ Before a user can call any protected endpoint they must first be registered:
 
 ## 3. Rate Limiting
 
-_TODO_
+All requests pass through a `RateLimitFilter` (implemented with **Bucket4j**).
+
+| Setting | Value |
+|---------|-------|
+| Limit | 60 requests per minute |
+| Window | Rolling 1-minute bucket |
+| Key (authenticated) | JWT `sub` claim (Google User ID) |
+| Key (unauthenticated) | `X-Forwarded-For` header, falling back to remote IP |
+
+When the limit is exceeded the server responds with:
+
+```
+HTTP 429 Too Many Requests
+```
+
+No `Retry-After` header is currently returned. Clients should back off and retry after 60 seconds.
+
+> **Note:** Rate limiting applies in the `!test` profile only. Tests run without rate limiting.
 
 ## 4. Endpoints