Idempotency

GET and search requests are read-only and safe to retry as often as you like. Two calls are not: POST /enrich and POST /jobs both do billable work, and retrying one without protection charges you twice. Send an Idempotency-Key:

curl -X POST https://api.unif.dev/v1/jobs \
  -H "Authorization: Bearer $UNIF_API_KEY" \
  -H "Idempotency-Key: nightly-enrich-2026-09-15" \
  -H "Content-Type: application/json" \
  -d '{ "type": "enrich", "input": { … } }'

If a request with that key already succeeded, Unif returns the original response without re-running anything.

Choosing a key

A key is any string up to 255 characters. What matters is that it identifies the intent, so a retry produces the same key and a genuinely new request does not.

Derive it from the work

nightly-enrich-2026-09-15, export-shops-us-2026-09 — deterministic, so a scheduler retry naturally reuses it.

Not a fresh UUID per attempt

A new UUID on each attempt makes every retry a new request, which is exactly what you were trying to prevent.

key = f"enrich-{tenant_id}-{batch_id}"          # stable across retries

Generating the key once and storing it with the task — before the first attempt — is what makes this work when the retry comes from a process that crashed and restarted.

Rules

Keys are retained for 24 hours

After that the key is forgotten and the same key starts fresh work. Retries should happen well inside that window.

A key is bound to its request body

Reusing a key with a different body returns 400 with idempotency_key_reused. This is a guard: it catches the bug where a key gets reused for work it does not describe.

Keys are scoped to a workspace

Two workspaces can use the same key string without colliding.

Only successes are replayed

If the original request failed with a 4xx or 5xx, the key is not retained — a retry runs the work properly rather than replaying a failure.

Concurrent retries

If a second request with the same key arrives while the first is still in flight, it returns 409 with idempotency_key_in_progress. Wait and retry:

def create_job(body, key):
    for attempt in range(5):
        resp = requests.post(
            "https://api.unif.dev/v1/jobs",
            headers={**AUTH, "Idempotency-Key": key},
            json=body, timeout=30,
        )
        if resp.status_code != 409:
            return resp.json()
        time.sleep(2 ** attempt)

    raise RuntimeError(f"idempotency key {key} stuck in progress")

This is the case that matters when two workers pick up the same queue message. One does the work, the other waits and then reads the same result — instead of both running an export.

Where it is not needed

Call	Needs a key?
`GET` anything	No — read-only
`POST /*/search`	No — read-only despite the verb
`POST /resolve`	No — deterministic and cheap
`POST /enrich`	Yes
`POST /jobs`	Yes
`POST /lists`, `POST /trackers`, `POST /webhooks`	Recommended — prevents duplicate objects
`POST /lists/{id}/items`	No — adds are naturally idempotent

The single most expensive mistake against this API is a job-creation retry without a key. An export that costs real credits, run twice because a scheduler timed out and tried again, is entirely avoidable with one header.

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

Idempotency

Choosing a key

Derive it from the work

Not a fresh UUID per attempt

Rules

Concurrent retries

Where it is not needed

​Choosing a key

Derive it from the work

Not a fresh UUID per attempt

​Rules

​Concurrent retries

​Where it is not needed

Choosing a key

Rules

Concurrent retries

Where it is not needed