Idempotency - Notvis Connect

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.

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

Use UUID v4

Generate a unique UUID for each logical operation. Don’t reuse keys across different operations.

Retry safely

On network timeouts, retry with the same idempotency key. You’ll get the original response back.

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

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.

​Overview

​How It Works

​Behavior

​Best Practices

Use UUID v4

Retry safely

​Replayed Responses

Overview

How It Works

Behavior

Best Practices

Replayed Responses