What is Idempotency Key?
A client-supplied unique key letting servers recognize retried requests and return the original result. Payment endpoints require one per checkout attempt so double-clicks and timeouts never charge twice.
Example
A Paddle checkout route stores the idempotency key with the order; when the client retries after a timeout, the server returns the stored order instead of creating a second charge.
What people get wrong
Generating a fresh key on every retry. The key must stay constant across retries of the same intent, or the server cannot match them.
Frequently asked questions
Where should the key live?
Clients generate one UUID per user intent and send it as a header; servers store it beside the order and match retries exactly.
How long must keys persist?
At least as long as clients may retry — hours for checkouts, longer for background jobs. Expire them only after the retry window closes.
Related terms
Idempotent HTTP Verbs
GET, PUT, and DELETE produce the same result when safely retried; POST does not promise that. BYOB server routes use idempotent verbs for mutations clients may repeat after network timeouts.
Retry, Backoff & Jitter
Retrying failed calls after growing delays with random spread, so a fleet does not stampede a recovering service. Exponential backoff plus jitter turns synchronized thundering herds into gentle background noise.
Paddle Checkout
Merchant-of-record billing: products, prices, client tokens, and notification webhooks handled by Paddle. Generated SaaS apps charge globally without assembling tax, invoicing, and dunning themselves.
REST Resource Design
Modeling an API as nouns with stable URLs — /projects/:id/messages — instead of action endpoints. Resource design makes caching, auth scoping, and client reasoning predictable across every route.
Dead-Letter Queue
A holding area for messages that exhausted every retry, preserved with full context for inspection. Dead letters stop poison events from blocking healthy traffic and give operators a deliberate replay path.
API Versioning
Evolving an API without breaking existing clients: versioned paths or headers, additive changes first, removals on a schedule. Versioning is a promise that yesterday’s integration keeps working tomorrow.