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

# Idempotency

> Retries can never double-charge: the Idempotency-Key header and a 24-hour replay window

Agents retry. Networks flake. Neither should ever cost you twice. Send an
`Idempotency-Key` header on any chargeable call, and a repeat of the same
request replays the first result instead of running and billing again.

```bash theme={null}
curl -H 'Authorization: Bearer nx_your_key' \
  -H 'Idempotency-Key: read-btc-2026-07-15-001' \
  'https://noxint.ai/api/v1/read?id=crypto:bitcoin'
```

## The key

An `Idempotency-Key` is 1 to 128 visible characters. Leading or trailing
whitespace and control characters are rejected. Choose a value unique to one
logical request, such as a UUID or a task-scoped string.

If you omit the header, the gateway generates a fresh key and echoes it back
in the `Idempotency-Key` response header. Every chargeable call is covered,
whether or not you thought about it.

## How replay works

| Situation                         | Result                                                                    |
| --------------------------------- | ------------------------------------------------------------------------- |
| Same key, same normalized request | Exact stored status, headers, and body replay, charged once, for 24 hours |
| Same key, different request       | `409 idempotency_conflict`                                                |
| Concurrent duplicate in flight    | `409 request_in_progress` with `Retry-After: 1`                           |

The replay window is 24 hours. Within it, the same key and the same
normalized request returns the identical response and charges the identical
single amount. Reusing a key for a different request is a conflict, so scope
each key to one request.

HTTP and MCP share one idempotency namespace for the same key and operation.
A retried MCP call can replay a result first produced over HTTP, and the
reverse holds too. One dedup ledger across both transports.

## Retries after a transient failure

A transient failure releases the hold so a retry can execute normally rather
than replaying an error. This applies to `408`, `425`, `429`, and `5xx`
responses. Reusing the same idempotency key on that retry is safe: because
the first attempt did not complete, the retry runs and settles once. Write
your retry loop naively; the gateway holds the invariant.