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

# Idempotency

> Use Idempotency-Key correctly for safe retries without duplicate usage.

Every `POST /v1/scrub` request requires an `Idempotency-Key` header.

```http theme={null}
Idempotency-Key: 018f47c2-9b0d-7c95-bf47-cd84c12f8912
```

An idempotency key identifies one **logical request** for the authenticated API
key.

## Rules

* Generate a random UUID or another opaque high-entropy value.
* Use a new key for every new logical request.
* Reuse the key only when retrying the exact same `country` and `phones` array.
* Preserve the original array order and values on a retry.
* Never derive the key from phone numbers, customer IDs, email addresses, or other PII.
* Keep the value between 1 and 255 visible ASCII characters with no spaces.

Exact retries are protected for at least seven days. DNC LATAM retains only a
keyed, non-reversible fingerprint—not the raw idempotency key, request body,
phone numbers, or response.

## Completed retry

When the original request completed successfully, an exact retry is
recalculated in memory and returns:

```http theme={null}
Idempotency-Replayed: true
```

The replay does not consume quota or write a second usage event.

## Concurrent retry

If the original request is still running, the API returns HTTP `409`:

```json theme={null}
{
  "error": "idempotency_request_in_progress",
  "message": "a request with this Idempotency-Key is still processing — retry shortly"
}
```

Respect the `Retry-After` header and retry the same payload with the same
idempotency key.

## Reused key with a different payload

If the same key is used with a different country or phone array, the API
returns HTTP `409`:

```json theme={null}
{
  "error": "idempotency_key_reused",
  "message": "this Idempotency-Key was already used with a different request payload"
}
```

Do not retry this response. Generate a new idempotency key for the new logical
request.

## Recommended retry record

Store the idempotency key beside your own internal job identifier and a
non-sensitive status. Do not store the phone-number payload merely to support
API retries if your own retention policy does not otherwise require it.