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

# Idempotency

> Send an Idempotency-Key so a retried request is run and charged once.

Send an `Idempotency-Key` header with a `POST` request. If the request times out or the connection drops, send it again with the same key. It runs once and is charged once.

```bash theme={null}
curl -s https://YOUR_AGENTIC_ID_HOST/v1/enrich \
  -H "Authorization: Bearer ic-live-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b1f4f0e-6f0a-4a39-9d57-0f3f7a1f2c10" \
  -d '{"contact":{"email":"alex.rivera@acme.example"},"max_credits":2}'
```

## Rules

| Rule | Detail |
| - | - |
| Header | `Idempotency-Key` |
| Format | 8 to 200 printable ASCII characters, no spaces. A UUID works. |
| Optional | Without the header, the request just runs |
| Methods | `POST` only: validate, resolve, enrich, find, discover, lookalike, feedback. `GET` requests ignore it. |
| Scope | Your workspace. Two workspaces can use the same key. |
| Kept for | 24 hours after the first request completes |
| What counts as the same request | The same endpoint and the same JSON body |

## What you get back

| Situation | Status | Result |
| - | - | - |
| First request with this key | 200 | The request runs. The answer is stored. |
| Same key, same body, first request completed | 200 | The stored answer, with the header `Idempotent-Replayed: true`. Not charged again. |
| Same key, same body, first request still running | 409 `idempotency.in_progress` | `Retry-After` of at most 5 seconds. Wait and send again. |
| Same key, different body or endpoint | 422 `idempotency.key_reused` | Use a new key for a new request |
| Key in a bad format | 400 `idempotency.key_invalid` | Send a valid key |

## When a key is freed

A key is freed when the request did nothing, so you can send it again.

| First request ended with | Key |
| - | - |
| 200 | Kept for 24 hours with the answer |
| Any 4xx, for example `request.invalid` or `credits.insufficient` | Freed. Nothing ran. |
| 503 `service.unavailable` with `sent: false` | Freed. Nothing was sent. |
| 504 `service.timeout`, or another 5xx | Held as in progress. The request may have run. |

## Ambiguous timeouts

A `504 service.timeout` carries `"ambiguous": true`. The request may have completed and charged.

**1. Send the same request with the same key**

If the first request finished, you get its answer with `Idempotent-Replayed: true`. If it is still marked as running, you get `409 idempotency.in_progress`.

**2. On 409, wait and repeat**

Wait for `Retry-After` and send again.

**3. Check before you give up**

`GET /v1/credits` lists the latest charges. Check it before you send the request with a new key.

> [!WARNING]
>
> A key whose request never recorded an answer stays in progress for 6 minutes, then frees. A retry with the same key after that runs the request again and could charge again. If you saw a `504`, check `GET /v1/credits` first.

## Recommendations

* Generate one key per logical request, and reuse it only for retries of that request.
* Do not reuse a key for a changed body. Changing `max_credits` or one identifier makes it a different request.
* Send the body with the same content on every retry.

The [MCP server](https://docs-agentic-id.icustomer.ai/mcp-server.md) and the [CLI](https://docs-agentic-id.icustomer.ai/cli.md) attach a key to every paid call and retry for you. The [SDK](https://docs-agentic-id.icustomer.ai/sdk.md) does not send one.

Related: [Errors](https://docs-agentic-id.icustomer.ai/errors.md), [Rate limits](https://docs-agentic-id.icustomer.ai/rate-limits.md), [Credits](https://docs-agentic-id.icustomer.ai/credits.md).


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