Technical Glossary
Idempotency in API Design
Exact Definition
Idempotency is the API design principle where making the same HTTP request multiple times produces identical server state — critical for financial transactions and payment APIs where network failures can cause duplicate requests.
Architectural Deep Dive
In unreliable networks, HTTP requests can be retried. Without idempotency, a retry of a payment POST could double-charge a customer. Idempotent APIs solve this by requiring clients to send a unique Idempotency-Key header with every state-changing request. The server records completed operations by key and returns the original response for duplicates without re-executing the logic. Stripe, PayPal, and all major payment APIs require idempotency keys.
The ERPStack Approach
We implement idempotency key tables in PostgreSQL with ON CONFLICT DO NOTHING semantics for all payment, payout, and inventory mutation API routes — as demonstrated in an artisan-manufacturing ERP build where 118 idempotent API routes eliminated all payout duplication errors.