ARTICLE
In distributed systems, networks are inherently unreliable. A client sends a request to charge a customer’s credit card, but the connection drops before the server can respond. Did the charge go through? Should the client retry?
Without idempotency, retrying that request could result in the customer being charged twice. This is unacceptable for financial infrastructure, which is why idempotency is a core principle when building payment systems.
What is an Idempotent Request?
An API request is idempotent if making it multiple times produces the same result as making it just once. For example, a GET request is naturally idempotent. Calling GET /users/123 ten times doesn’t change the user’s data.
However, POST requests—like POST /charges—are not idempotent by default.
Implementing Idempotency Keys with Cord
To safely retry POST requests, the Cord API requires clients to send an Idempotency-Key header. This key is a unique identifier (usually a V4 UUID) generated by your client application.
POST /v1/charges HTTP/1.1
Host: api.cord.com
Authorization: Bearer sk_test_123
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
{
"amount": 5000,
"currency": "usd"
}
When you send this request, Cord checks a fast, distributed cache for the idempotency key.
- If the key is new: The transaction is processed, and the HTTP response is securely stored.
- If the key is found, and the original request is still processing: The API holds the new request open and waits for the original to finish.
- If the key is found, and the original request finished: Cord immediately returns the cached HTTP response, without executing the transaction again.
Why this matters for developers
By integrating idempotency keys, you can implement aggressive retry logic in your frontend or mobile applications without fear of data corruption or duplicate transactions. When using Cord’s SDKs, these keys are generated and managed automatically, ensuring that transient network failures are handled seamlessly behind the scenes.
In distributed systems, networks are inherently unreliable. A client sends a request to charge a customer's credit card, but the connection drops before the server can respond. Did the charge go through? Should the client retry?
Without **idempotency**, retrying that request could result in the customer being charged twice. This is unacceptable for financial infrastructure, which is why idempotency is a core principle when building payment systems.
## What is an Idempotent Request?
An API request is idempotent if making it multiple times produces the same result as making it just once. For example, a `GET` request is naturally idempotent. Calling `GET /users/123` ten times doesn't change the user's data.
However, `POST` requests—like `POST /charges`—are not idempotent by default.
## Implementing Idempotency Keys with Cord
To safely retry `POST` requests, the Cord API requires clients to send an `Idempotency-Key` header. This key is a unique identifier (usually a V4 UUID) generated by your client application.
```http
POST /v1/charges HTTP/1.1
Host: api.cord.com
Authorization: Bearer sk_test_123
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
{
"amount": 5000,
"currency": "usd"
}
```
When you send this request, Cord checks a fast, distributed cache for the idempotency key.
1. **If the key is new:** The transaction is processed, and the HTTP response is securely stored.
2. **If the key is found, and the original request is still processing:** The API holds the new request open and waits for the original to finish.
3. **If the key is found, and the original request finished:** Cord immediately returns the cached HTTP response, without executing the transaction again.
## Why this matters for developers
By integrating idempotency keys, you can implement aggressive retry logic in your frontend or mobile applications without fear of data corruption or duplicate transactions. When using Cord's SDKs, these keys are generated and managed automatically, ensuring that transient network failures are handled seamlessly behind the scenes.