Idempotency - Noxint Docs

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.

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.

​The key

​How replay works

​Retries after a transient failure

The key

How replay works

Retries after a transient failure