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

# Idempotency

> Retry a billable request safely with an Idempotency-Key.

Networks fail. When a request times out you cannot tell whether it ran, and repeating a
billable lookup could charge you twice. Send an `Idempotency-Key` header on every operation that
documents one, and a retry becomes safe.

```bash theme={null}
curl https://app.loice.ai/api/v1/find \
  -H "Authorization: Bearer $LOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-6c55-4c1e-9d0b-0f1e8b6a2c11" \
  -d '{"mode":"email","name":"Satya Nadella","company":"microsoft.com"}'
```

## How it behaves

* **The same key with the same request** replays the original outcome. It is not run again and
  not charged again; the response says `"replay": true`.
* **The same key with a different request** is refused with `409 idempotency_conflict`. Use a
  new key for new work.
* **The same key while the first request is still running** is refused with
  `409 idempotency_in_progress`. Retry after it finishes to receive its outcome.
* A malformed key is refused with `400 validation_error`.

## Choosing a key

A key is 1 to 255 printable ASCII characters. Use a fresh UUID per logical action, or derive it
from your own record, such as `contact-8812-find`, so that re-running a batch replays instead of
re-billing. Keys are scoped to your workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.