Break This API

Duplicate requests, lost responses, old clients, unknown enum values, huge payloads, rate limits, dead dependencies, slow consumers, replayed webhooks. Pick a failure, toggle contract protections, and see where the failure stops — or how far it travels.

Choose a failure to run
Break This API: Duplicate Payment Request
A customer was charged twice for one checkout — support has both provider receipts, and the order table shows a single order.
CONTRACT FAILS
  1. 1 · Client → API
    Client POSTs /payments
    The checkout submits a card charge for $86.00. The request is well-formed and authorized — nothing is wrong yet.
  2. 2 · API → Client
    Response is lost
    The API charges the provider and writes the payment row, but the 201 dies on the way back — a dropped connection, a proxy timeout. The client cannot distinguish "never happened" from "happened, reply lost".
  3. 3 · Client → API
    Client retries the POST
    The client resubmits the identical request. Without a key the API sees a brand-new payment and starts a second charge.
  4. 4 · API → Provider
    Provider charges again
    The API calls the payment provider with a fresh internal reference, so the provider has no way to recognize the repeat either.
  5. 5
    Both charges settle
    Two captures clear overnight. Nothing in the system compares provider settlements against orders, so the duplicate surfaces as a customer complaint or a chargeback.
Contract protections — each has a cost
Idempotency key storelesson →

Require an `Idempotency-Key` on POST /payments; on a repeat, replay the stored result instead of charging again.

Cost: A keyed result store with expiry, and a documented client obligation to generate and reuse the key across retries.

Provider-side dedup referencelesson →

Send the provider a deterministic reference derived from the order, so the provider itself rejects a second capture for the same charge.

Cost: Reference lifecycle tied to your order model, and handling the provider's "already exists" response as success.

Reconciliation alertlesson →

Compare provider settlement records against orders daily and alert on any order with more than one capture.

Cost: A reconciliation job, provider report ingestion, and someone on the hook to triage alerts.

If the failure completes
  • • Customers are double-charged; refunds and chargebacks cost money and trust.
  • • Finance cannot reconcile revenue against orders until the duplicates are found by hand.
  • • The client team starts avoiding retries entirely, trading duplicate charges for dropped payments.
What telemetry shows
  • • Provider captures per order exceed 1 in reconciliation data.
  • • A spike in POST /payments requests whose bodies hash identically within a short window.
  • • Refund volume rising in step with client-side timeout rates.
Every scenario is a conceptual simulation of contract behavior. The question each one asks is the same: does the API still behave predictably when this happens — and would you notice?