> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notvis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Prevent duplicate API requests with idempotency keys.

## Overview

Network issues can cause requests to fail ambiguously — you don't know if the server processed it or not. Idempotency keys let you safely retry requests without creating duplicate messages.

## How It Works

Include an `Idempotency-Key` header with a unique value (we recommend a UUID v4) on any `POST` request. If we receive a duplicate request with the same key, we return the original response instead of processing it again.

```bash theme={null}
curl -X POST https://api.notvis.com/v1/sms/messages \
  -H "Authorization: Bearer nc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "to": "+919876543210",
    "dlt_template_id": "1107161234567890",
    "variables": { "1": "123456" }
  }'
```

## Behavior

| Scenario                    | Result                                                          |
| --------------------------- | --------------------------------------------------------------- |
| First request with key      | Processed normally, response cached                             |
| Same key within 24 hours    | Returns cached response with `Idempotent-Replayed: true` header |
| Same key after 24 hours     | Processed as a new request                                      |
| No `Idempotency-Key` header | Request processed normally, no deduplication                    |

## Best Practices

<CardGroup cols={2}>
  <Card title="Use UUID v4" icon="fingerprint">
    Generate a unique UUID for each logical operation. Don't reuse keys across different operations.
  </Card>

  <Card title="Retry safely" icon="rotate">
    On network timeouts, retry with the same idempotency key. You'll get the original response back.
  </Card>
</CardGroup>

<Warning>
  Idempotency keys are scoped per API key. The same key used by different API keys are treated as separate requests.
</Warning>

## Replayed Responses

When a response is replayed from cache, the response includes the header:

```
Idempotent-Replayed: true
```

Your application can check this header to know if the response was a cached replay.