Appearance
Idempotency Keys
TiruPay is a payment system - network issues or client timeouts can lead you to retry a request without knowing whether the original attempt actually succeeded. Idempotency keys let you retry a POST or PATCH request safely: if the operation already ran, TiruPay returns the original response instead of performing it again.
Using an Idempotency Key
Send an Idempotency-Key header with any POST or PATCH request:
http
POST /orders HTTP/1.1
Authorization: Bearer <token>
Idempotency-Key: 3f29c1a0-6b2e-4e9a-9c1a-2f0c4d8b7a11Generate a fresh, unique key (a UUID works well) for every distinct logical operation. Reuse the same key only when retrying that exact same operation - a key reused with a different query string or body is rejected (see below).
Requires authentication
The idempotency key is scoped to the caller. It only applies if the request carries a valid Authorization: Bearer token - without one, TiruPay cannot resolve who the key belongs to, so the header is ignored and the request is processed normally.
Behavior
- First request with a key: processed normally. The response is cached against the key.
- Retry with the same key, after completion: returns the original response - same status code, body, and headers - without running the operation again.
- Retry with the same key, while the original is still processing: rejected with
409 Conflict("Request already in progress."), since concurrent duplicate calls can't both be answered from a cached result yet. - Retry with the same key, after the original failed: an error response (anything other than a
2xx, or a redirect up to302) is never cached. The key is released, so the retry runs the operation again instead of replaying the failure - only a genuinely successful response is ever safe to replay. - Same key, different request: if the query string or body differs from the request that first used the key, the call is rejected with
422 Unprocessable Contentand nothing runs. Use a new key for a new operation.
Every response to a request that carried an Idempotency-Key - whether it was just executed or replayed from cache - echoes that key back in an X-Idempotency-Key response header.
The header doesn't tell you which one happened
X-Idempotency-Key always contains the same value you sent, on both a freshly executed response and a replayed one - it confirms the key was recognized, but it does not by itself tell you whether the operation actually ran again or was served from cache. If you need to know that, check the state of the underlying resource (e.g. does the order already have a payment attached).
Only successful JSON responses are cached
Two kinds of responses are never cached, and in both cases the key is released instead, so a retry with the same key runs the operation again rather than replaying a stale response:
- The response isn't JSON (e.g. a file download).
- The response is an error (anything other than a
2xx, or a redirect up to302).
Fails closed
If TiruPay can't reach its idempotency store, requests carrying an Idempotency-Key fail with 503 Service Unavailable rather than proceeding without the idempotency guarantee. Retry after a short delay.
Example: Finalizing an Order
Finalizing an order charges the customer's selected payment method - exactly the kind of call you don't want to accidentally run twice because a request timed out.
http
POST /orders/ord_456/finalize?redirect=false HTTP/1.1
Authorization: Bearer <token>
Idempotency-Key: 3f29c1a0-6b2e-4e9a-9c1a-2f0c4d8b7a11
Content-Type: application/json
{
"payment_method_id": "pm_abc123"
}If this call succeeds but the response never reaches you (timeout, dropped connection, etc.), retry it with the same Idempotency-Key. TiruPay returns the original response - the order is charged once, not twice.
http
HTTP/1.1 200 OK
X-Idempotency-Key: 3f29c1a0-6b2e-4e9a-9c1a-2f0c4d8b7a11
Content-Type: application/json
{
"url": "https://checkout.example/pay/..."
}Pass redirect=false for idempotent calls
By default this endpoint answers with an HTTP redirect, not JSON - and only JSON responses are cached for idempotency (see above). Without redirect=false, a retried request would run finalize again instead of replaying the original result. Always pass redirect=false when you intend to rely on the idempotency key here.
Good to Know
Keys expire
A completed response is only kept for a limited retention window. After it expires, reusing the same key runs the operation again rather than replaying the old result - don't rely on keys as permanent records of past requests.
Relationships
- Rate Limits - Prefer retrying with the same idempotency key over blind retries, so repeated attempts at one operation don't also eat into your rate limit allowance.
- Orders and Payments - The endpoints where safe retries matter most, since a duplicate call could otherwise mean a duplicate charge or a duplicate order.