Idempotency

Networks lie. A client sends path, the request reaches the server and creates a project, but the 201 response is lost in transit. The client times out and retries. Without an idempotency key, you now have two identical projects.

With an idempotency key, Alloovium caches the original response for 24 hours keyed on key. The second request replays the first response verbatim — status, headers, and body — and does not re-execute the handler.

http
POST /api/v2/vault/projects HTTP/1.1
Host: api.alloovium.com
Authorization: Bearer ak_live_...
Idempotency-Key: create-tower-2026-04-08
Content-Type: application/json

{"name": "Downtown Tower", "project_type": "commercial"}

The key must match the pattern pattern — 1 to 255 characters from chars. Anything else returns error.

GETs ignore the header entirely. If you attach header to a GET the API will neither cache nor reject it.

When a key matches a cached 2xx response, the server returns the full original response and adds:

http
HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true

{"id": "8f2e3c1a-...", "name": "Downtown Tower", ...}

The header header is the signal that no work was performed. Use it for observability — log it, expose it in traces — but do not branch on it. The response body is exactly what the first call returned.

If you reuse an idempotency key but send a different body, the server does not overwrite the original. Instead you get:

json
{
  "type": "https://api.alloovium.com/errors/idempotency_key_reused",
  "title": "Idempotency key reused",
  "status": 422,
  "detail": "The Idempotency-Key was previously used with a different request body.",
  "code": "idempotency_key_reused"
}

This is a hard contract: once a key is bound to a body, that binding is immutable for the 24-hour window. The server hashes a canonical form of the body at first write and compares on every replay.

If the original request is still running when a retry arrives with the same key, the server returns:

json
{
  "type": "https://api.alloovium.com/errors/idempotency_in_progress",
  "title": "Idempotency key in progress",
  "status": 409,
  "detail": "A request with this Idempotency-Key is still in progress. Retry shortly.",
  "code": "idempotency_in_progress"
}

http
HTTP/1.1 409 Conflict
Retry-After: 5

The in-progress lock has a 60-second TTL — if the original handler dies without caching a response, the lock expires and the next retry executes for real. Respect the header header; a 5-second backoff is usually enough to catch the cached result.

Idempotency requires buffering the request body so the server can hash it. Bodies above limit bypass idempotency entirely — they execute normally and never write to the cache, regardless of whether you attached a key.

python
import time, uuid, httpx

def create_project(client, name):
    idem_key = f"create-project-{uuid.uuid4()}"
    body = {"name": name, "project_type": "commercial"}

    for attempt in range(5):
        resp = client.post(
            "https://api.alloovium.com/api/v2/vault/projects",
            json=body,
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Idempotency-Key": idem_key,
            },
        )

        # Success (fresh or replayed) — both are fine
        if resp.is_success:
            if resp.headers.get("Idempotent-Replayed") == "true":
                log.info("recovered from earlier success")
            return resp.json()

        # Original still in progress — wait and retry with the SAME key
        if resp.status_code == 409 and resp.json().get("code") == "idempotency_in_progress":
            time.sleep(int(resp.headers.get("Retry-After", "5")))
            continue

        # Rate limited — honour Retry-After
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", "5")))
            continue

        # 5xx transient — exponential backoff, same key
        if 500 <= resp.status_code < 600:
            time.sleep(min(30, 2 ** attempt))
            continue

        # 4xx other than 429/409 — do not retry
        resp.raise_for_status()

    raise RuntimeError("max retries exhausted")

Every request gets an header header in the response — see Errors. When an idempotent replay happens, the replayed response carries the original request ID, not the current one. If you are debugging a double-submit scenario, log both the incoming request ID (from your own client) and the xheader returned by the server — they will match on replay and diverge on a fresh call.

• Rate Limits — retry strategy for 429 and 5xx.
• Errors — full error code reference including codes variants.