Idempotent API Design for Financial Reliability
In financial systems, a "Ghost Transaction" is a nightmare. This happens when a network timeout occurs, and the client retries a request that was actually partially processed. To solve this, we must design Idempotent APIs.
The Core Concept
An idempotent operation is one that can be performed multiple times without changing the result beyond the initial application.
[!IMPORTANT] Idempotency is not optional in Fintech. Every POST/PATCH request that moves money must be idempotent to protect against network instability.
Idempotency Key Workflow
The most robust pattern involves an Idempotency-Key header provided by the client (usually a UUID).
Arch Note
Interactive logic enabled. Click components in expanded view for technical service definitions.
Handling Retries
When a client retries with the same key, the service should:
- If Processing: Return
409 ConflictorProcessing. - If Completed: Return the cached response from the first successful attempt.
Failure Scenarios
| Scenario | Result without Idempotency | Result with Idempotency |
|---|---|---|
| Client Retry on Timeout | Double Charge (2x Withdrawal) | Single Charge (2nd Req returns cached 200) |
| Concurrent Double-Click | Parallel race condition | Atomic Lock (2nd Req rejected immediately) |
| Internal Server Error | Partial data, retry might fail | Deterministic recovery via state machine |
Consultant's Implementation Checklist
- Database Constraints: Use a
UNIQUEconstraint on theidempotency_keycolumn in your SQL database as the ultimate source of truth. - Standardized Header: Use a standard header name like
X-Idempotency-Key. - Expiration Policy: Set a TTL for your idempotency cache (e.g., 24-48 hours) to prevent Redis memory bloat.
- deterministic Response: Ensure the cached response includes the same body and status code as the original.
[!TIP] Pro-Tip: For critical H2H banking integrations, always log the
request_payloadalongside theidempotency_keyto audit any attempts to reuse the same key with different amounts or currencies.
Building idempotent systems is about moving from "hope-based" engineering to "deterministic-based" engineering.