> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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:

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:

```bash theme={null}
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:

```json theme={null}
{
  "msg": "Concurrent requests with same idempotency key, please try again later"
}
```

## See also

* [Authenticating with the API](/reference/authenticating-with-the-api): API keys, roles, and IP restrictions.
* [Rain API overview](/reference/rain-api): conventions, rate limits, and endpoint groups.