Idempotency Explained: Why Your API Needs It

In a perfect world, networks never fail, servers never crash, and every API request succeeds on the first try. In the real world, things go wrong. Requests time out, connections drop, and clients retry. Without idempotency, these retries can lead to serious problems, like charging a customer twice for the same order.

What is Idempotency?

An idempotent operation is one that has no additional effect if it is called more than once with the same input parameters. In the context of APIs, it means that making the same request multiple times should result in the same state on the server as making it once.

Most GET requests are naturally idempotent. Fetching a user profile ten times doesn't change the user profile. However, POST requests—which typically create resources or trigger actions—are not idempotent by default.

The Double-Charge Problem

Imagine a client sending a request to process a $100 payment.

1. The client sends the POST /payments request.
2. The server receives the request, processes the payment successfully, but the network connection drops before the server can send the 200 OK response.
3. The client, seeing a timeout or connection error, assumes the request failed and retries the exact same POST /payments request.
4. The server receives the second request, treats it as a new payment, and charges the customer another $100.

The customer is now out $200 for a single order. This is the "double-charge" problem, and it's a nightmare for both users and developers.

How Idempotency Keys Work

The standard solution is to use an Idempotency Key. This is a unique value generated by the client and sent along with the request, typically in an HTTP header like Idempotency-Key.

When the server receives a request with an idempotency key, it follows this logic:

• Check: Has this key been seen before?
• If No: Process the request normally and store the result (status code and body) associated with that key.
• If Yes: Don't re-run the logic. Simply return the previously stored result.

Implementing Idempotency with FetchAPI

Building a robust idempotency system is harder than it looks. You need a fast, reliable storage layer to track keys, handle race conditions where two identical requests arrive at the same time, and manage key expiration.

FetchAPI handles all of this for you. When you relay a request through FetchAPI, you can provide an Idempotency-Key header. We ensure that your destination server only receives the request once, even if you retry the call to FetchAPI multiple times.

Example: JavaScript

const response = await fetch('https://api.fetchapi.dev/v1/fetch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer relay_sk_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order_123_abc', // Unique key for this action
    'X-Fetch-Url': 'https://api.yourserver.com/payments'
  },
  body: JSON.stringify({
    amount: 10000,
    currency: 'usd',
    customer_id: 'cus_987'
  })
});

Example: cURL

curl -X POST https://api.fetchapi.dev/v1/fetch \
  -H "Authorization: Bearer relay_sk_..." \
  -H "Idempotency-Key: unique-request-id-001" \
  -H "X-Fetch-Url: https://api.yourserver.com/orders" \
  -d '{"item": "laptop", "quantity": 1}'

Conclusion

Idempotency isn't just a nice-to-have; it's a requirement for any API that handles critical actions like payments, bookings, or state changes. By using FetchAPI, you get production-grade idempotency out of the box, allowing you to build resilient systems without the architectural overhead.