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.

Real endpoints from the catalog — every request above is served, and every status code shown is one that endpoint actually returns.

How to practise it

Send requests until you get a 429, then read Retry-After and wait exactly that long before retrying.
Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on successful calls and throttle from them, rather than waiting to be refused.
Verify your retry policy applies backoff and a ceiling — an immediate retry loop on a 429 is indistinguishable from an attack.
Check that a 429 is not counted as a permanent failure in your circuit breaker.
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

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 39 mock REST APIs

Last updated 6 September 2026