# Idempotency key

An idempotency key is a caller-chosen string sent with a create request so that a retry of the same request returns the original result instead of creating a second one.

Date: 2026-09-10

An idempotency key is a caller-chosen string sent with a create request so that a retry of the same request returns the original result instead of creating a second one. It exists because a network timeout tells you nothing about whether the server acted.

## What Spaw answers

Send `Idempotency-Key` (1 to 128 printable ASCII characters) when creating a bulk job. A retry carrying the same key and the same request answers `200` with the same body — the same job, the same webhook secret — and the header `Idempotent-Replayed: true`. The same key with a *different* request answers [`409 IDEMPOTENCY_KEY_REUSED`](/docs/errors/IDEMPOTENCY_KEY_REUSED) rather than quietly returning the wrong job.

The request is fingerprinted as the lookup will read it, with a list-level country already folded into each item, so a retry that spells the same request differently still replays rather than being refused.

## Where it does not apply

Single lookups have no idempotency key and do not need one: a repeat of the same value inside seven days is free anyway, which gives a retried lookup the same billing outcome without any bookkeeping.

Reference: https://spaw.co/glossary/idempotency-key