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

# Idempotency

> Prevent duplicate search execution and duplicate billing.

Add an `Idempotency-Key` header to each logical Entity Search or Contact Search request. The header is optional today, but strongly recommended for production clients.

```http theme={null}
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

## Rules

* Keys are trimmed and must be no more than 128 characters.
* The idempotency scope is the API credential plus the key. The same key used with another API key is a different request.
* Reusing a key with the same canonical request returns `409 request_already_exists`.
* Reusing a key with a different canonical request returns `409 idempotency_error`.
* lev8 does not execute or bill the upstream search a second time for either conflict.
* The current API does not replay a previous SSE or JSON response.

## Recommended pattern

1. Generate a UUID when your application creates a logical search job.
2. Persist it with the job before making the HTTP request.
3. Use the same key only to determine whether that exact job was already admitted.
4. Do not automatically create a new key after a timeout or partial stream. Preserve the request ID and resolve the original state first.

<Warning>
  A failed or interrupted request can retain billing state for reconciliation. Blindly retrying with a new key can start a second billable search.
</Warning>