Idempotency

Idempotency is a critical concept for building reliable API integrations. This guide explains how Maraboo implements idempotency and how to use it effectively in your applications.

What is Idempotency?

Idempotency ensures that making the same API request multiple times has the same effect as making it once. This is essential for:

• Preventing duplicate transactions (e.g., charging a customer twice)
• Safe retries when network issues occur
• Handling timeouts without risk of duplication
• Building resilient applications that can recover from failures

Example Scenario

Without idempotency:

1. Your app sends: "Create payment for $100"
2. Network timeout occurs
3. Your app retries: "Create payment for $100" again
4. Result: Customer charged $200 (duplicate payment!)

With idempotency:

1. Your app sends: "Create payment for $100" with idempotency key "abc123"
2. Network timeout occurs
3. Your app retries: "Create payment for $100" with same key "abc123"
4. Result: Customer charged $100 once (duplicate prevented)

How Idempotency Works

Maraboo uses an Idempotency Key to identify duplicate requests:

1. You include a unique X-Idempotency-Key header in your request
2. Maraboo processes the request and stores the result
3. If you send the same request with the same key again:
   • ✅ Maraboo returns the original response without re-processing
   • ✅ No duplicate action is taken
   • ✅ Same status code and response body as the original