Idempotency for APIs

What is idempotency?

Idempotency ensures that making the same API request multiple times has the same effect as making it once. This is crucial for preventing duplicate operations when network issues, timeouts, or retries occur. When you include an Idempotency-Key header in your request, Rain’s API will:

Process the request only once, even if you send it multiple times
Return the same response for subsequent requests with the same key
Prevent duplicate charges, transactions, or other operations

How it works

When you make a POST, PUT, PATCH, or DELETE request with an Idempotency-Key header:

First request: Rain processes your request normally and caches the response for 24 hours
Duplicate requests: If you send the same request again with the same idempotency key, Rain returns the cached response immediately without re-processing

The idempotency key must be a unique string (for example, a UUID) that you generate for each distinct operation. Reuse the same key only for retries of the same operation.

Specifications

Idempotency-Key must be 64 characters long at most. A longer key doesn’t fail the request; Rain processes the request normally but skips idempotency entirely, so retries with that key are not deduplicated. Idempotency is supported for:

POST
PUT
PATCH
DELETE

Idempotency responses are stored in our system for 24 hours from the time of request arrival.

Response headers

All responses include these headers to help you understand the idempotency status:

Header	Description
`Idempotency-Key`	The idempotency key used for the request
`Idempotency-Cached`	`true` if returning a cached response, `false` for new responses

Best practices

Follow these practices to use idempotency keys safely:

Generate unique keys: Use UUIDs or similar unique identifiers for each operation
Reuse keys for retries: If a request fails or times out, retry with the same idempotency key
Don’t reuse keys: Never reuse an idempotency key for different operations
Set reasonable timeouts: Cached responses expire after 24 hours
Handle 429 responses: If you receive a concurrent request error, wait briefly and retry

Example

Here’s a sample request creating a card with an idempotency key:

curl --request POST \
  --url https://api-dev.rain.xyz/v1/issuing/users/{userId}/cards \
  --header 'Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: IDEMPOTENCY_KEY' \
  --data '{
  "type": "physical",
  "status": "notActivated",
  "limit": {
    "amount": 123,
    "frequency": "per24HourPeriod"
  },
  "configuration": {
    "displayName": "<string>",
    "productId": "<string>",
    "productRef": "<string>",
    "virtualCardArt": "<string>"
  },
  "shipping": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postalCode": "<string>",
    "countryCode": "<string>",
    "method": "standard",
    "phoneNumber": "<string>",
    "firstName": "<string>",
    "lastName": "<string>"
  },
  "bulkShippingGroupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "billing": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postalCode": "<string>",
    "countryCode": "<string>",
    "country": "<string>"
  }
}'

If this request fails due to a network timeout, you can safely retry with the same Idempotency-Key. The second request will return the same response as the first request, including the Idempotency-Cached: true header.

Error handling

Server errors (5xx)

If your request results in a server error (status code 500 or higher), the response is not cached. You can safely retry with the same idempotency key, and the request will be processed again.

Client errors (4xx)

Client errors (status code 400-499) are cached. If you retry with the same idempotency key, you’ll receive the same error response.

Concurrent requests

If you send multiple requests with the same idempotency key at the same time, only the first request will be processed. Other requests will receive a 429 Too Many Requests response:

{
  "msg": "Concurrent requests with same idempotency key, please try again later"
}

Overview

Compliance

Cards

Payments

Webhooks

Webhook Events

Idempotency for APIs

What is idempotency?

How it works

Specifications

Response headers

Best practices

Example

Error handling

Server errors (5xx)

Client errors (4xx)

Concurrent requests

See also

​What is idempotency?

​How it works

​Specifications

​Response headers

​Best practices

​Example

​Error handling

​Server errors (5xx)

​Client errors (4xx)

​Concurrent requests

​See also

What is idempotency?

How it works

Specifications

Response headers

Best practices

Example

Error handling

Server errors (5xx)

Client errors (4xx)

Concurrent requests

See also