Testing rate limits, 429s and backoff

Almost nobody tests rate limiting, because a well-behaved API will not rate limit you on demand — and so the retry policy that turns a slowdown into an outage ships untested. The Coffee Shop API enforces a genuine quota over a live window, so you can exceed it deliberately and watch it reopen.

How to practise it

1. Send requests until you get a 429, then read Retry-After and wait exactly that long before retrying.
2. Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on successful calls and throttle from them, rather than waiting to be refused.
3. Verify your retry policy applies backoff and a ceiling — an immediate retry loop on a 429 is indistinguishable from an attack.
4. Check that a 429 is not counted as a permanent failure in your circuit breaker.
5. Use the Fault Injection API to combine a rate limit with intermittent 503s and see whether your client still converges.

APIs to try it on

• Coffee Shop API — Drinks & orders. Home of the legendary 418. (6 endpoints)
• Fault Injection API — Latency, status codes, malformed payloads & flaky responses. (4 endpoints)

Status codes involved

• 429 Too Many Requests
• 503 Service Unavailable

Other techniques

• Pagination testing — Practise page-number and cursor pagination, and the edge cases that break clients: the last partial page, an out-of-range page, and a total count that disagrees with what you collected.
• Idempotency key testing — Send the same write twice with an Idempotency-Key and confirm the operation happens once — the mechanism that stops a network retry becoming a duplicate charge.
• ETag and If-Match testing — Provoke a 412 Precondition Failed by writing with a stale ETag — the check that stops two clients silently overwriting each other.
• Webhook signature testing — Register a callback, trigger a delivery, verify its HMAC signature, and confirm a tampered payload is rejected.
• OAuth and JWT testing — Run real client-credentials, authorization-code and device-code flows, then test what your client does when the token expires mid-session.
• Negative testing — Provoke 400, 401, 403, 404, 409, 418, 422, 429, 500 and 503 deliberately, and check your client handles each one differently.
• Async job testing — Start a long-running job, follow the 202 and its Location header, and poll to completion — including the failure and timeout paths.

Getting started guide · All 37 mock REST APIs