Testing idempotency keys and safe retries

A POST that times out is the hardest case in client design: the request may have succeeded, and you cannot tell. Idempotency keys resolve it by making the retry safe. The APIs below accept an Idempotency-Key header and replay the original response rather than performing the work again.

How to practise it

1. Create a resource with an Idempotency-Key, then send the identical request again and confirm you get the original response — same id, same body.
2. Change the body but keep the key, and see how the API reports the mismatch.
3. Send the same body with a different key and confirm you get two distinct resources, which is the correct behaviour.
4. Transfer money on the Bank API with a repeated key and verify the balance moved exactly once.
5. Combine with the Fault Injection API: inject a timeout, retry with the same key, and check the end state is correct.

APIs to try it on

• Friends API — Characters, episodes & quotes from the coffee-house gang. (14 endpoints)
• Bank API — Accounts, transfers & cursor pagination. Home of the 402. (9 endpoints)
• Fault Injection API — Latency, status codes, malformed payloads & flaky responses. (4 endpoints)

Status codes involved

• 200 OK
• 201 Created
• 409 Conflict

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.
• Rate limit testing — Trigger a real 429 with Retry-After and X-RateLimit headers, and verify your client backs off instead of retrying straight into the limit.
• 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