Idempotency for APIs

Use an Idempotency-Key header to safely retry Rain API requests without duplicating operations.

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:

1. First request: Rain processes your request normally and caches the response for 24 hours
2. 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.

Rain supports idempotency for:

• POST
• PUT
• PATCH
• DELETE

Rain stores idempotency responses for 24 hours from the time the request arrives.

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:

1. Generate unique keys: Use UUIDs or similar unique identifiers for each operation
2. Reuse keys for retries: If a request fails or times out, retry with the same idempotency key
3. Don’t reuse keys: Never reuse an idempotency key for different operations
4. Set reasonable timeouts: Cached responses expire after 24 hours
5. 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), Rain does not cache the response. You can safely retry with the same idempotency key, and Rain processes the request again.

Client errors (4xx)

Rain caches client errors (status code 400-499). 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, Rain processes only the first request. Other requests will receive a 429 Too Many Requests response:

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

See also

• Authenticating with the API: API keys, roles, and IP restrictions.
• Rain API overview: conventions, rate limits, and endpoint groups.