Idempotency

Network calls fail in ambiguous ways: a request times out, but did the server process it? On a billable POST — sending a campaign, revealing a contact, kicking off a render — a blind retry could charge you twice. Idempotency keys make retries safe: AI92 recognizes the retry and returns the original result instead of running the operation again.

How it works

Send an X-AI92-Idempotency-Key header on any POST or PATCH. AI92 stores the first response under (your account, key). If you send the same key with the same request body again, you get the stored response back — the operation does not re-run and you are not charged a second time.

curl -X POST https://api.ai92.ai/v1/contacts/reveal \
  -H "Authorization: Bearer ai92_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-AI92-Idempotency-Key: 6f9619ff-8b86-d011-b42d-00cf4fc964ff" \
  -d '{"person_id": "ph_8842", "mode": "email"}'

import uuid, httpx

idem_key = str(uuid.uuid4())  # generate ONCE, reuse across retries of THIS request
r = httpx.post(
    "https://api.ai92.ai/v1/contacts/reveal",
    headers={
        "Authorization": "Bearer ai92_live_YOUR_KEY",
        "Content-Type": "application/json",
        "X-AI92-Idempotency-Key": idem_key,
    },
    json={"person_id": "ph_8842", "mode": "email"},
)

Generating keys

• Use a UUID v4 (or any unique, hard-to-guess string).
• Generate the key once per logical operation, on the client, before the first attempt — and reuse that same key for every retry of that operation.
• Do not reuse a key for a genuinely new operation. Each distinct action gets its own key.

A good pattern: derive the key deterministically from your own domain identifier (e.g. reveal:ph_8842:run-2026-06-21) so even a process crash-and-restart retries with the same key.

Replay semantics

When AI92 serves a stored response, it adds:

X-AI92-Idempotent-Replay: true

The body is byte-for-byte the original response, with the original status. Treat a replay exactly like a first success — your downstream logic should already be safe to run on it (and the operation was only performed, and billed, once).

Conflict semantics

If you reuse a key with a different request body, that's almost always a bug — you've accidentally recycled a key for a new operation. AI92 refuses it:

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSE",
    "message": "Same idempotency key used with a different request body. Use a new idempotency key for new requests.",
    "status": 409
  }
}

The fix is always: new operation → new key.

Scope and lifetime

• Per account. Keys are namespaced to your account; another account using the same string never collides with yours.
• POST and PATCH only. GET/DELETE are already safe to repeat; the header is ignored there.
• 24-hour window. Stored responses are retained for 86,400 seconds (24h). Retry within that window to get the replay; after it, the same key starts fresh.

Best practices

• Always send a key on billable writes — reveals, sends, renders, enrich, bulk.
• Pair idempotency with retries. Your 429/503 backoff loop and your idempotency key are a single mechanism: the key is what makes the retry safe.
• One key per attempt-set, not per attempt. Reusing the key across attempts is the whole point.
• Store the key with your job/record so a worker that restarts mid-flight resumes with the same key.