Idempotency

Where enforcement is enabled, an idempotency key lets a repeated POST or PATCH replay its cached response. Check availability and caching limits before relying on it to prevent duplicate work.

Idempotency-Key enforcement is live on the Extended API today and rolling out to the Main API. Including the header on Main API requests is forward-compatible: today it has no effect, and once the rollout completes, retries with the same key replay the cached response.

How it works

Generate a key

Generate a unique key per logical request, typically a UUID, a hash, or your own primary key.

Send it on the first attempt

Add an Idempotency-Key header to your POST or PATCH.

Retry with the same key and body

If the request times out or fails partially, retry with the exact same key and exact same body.

Receive the cached response

Where idempotency enforcement is enabled, Spotzee replays the cached status and body. The response header Idempotent-Replayed: true confirms a replay; do not rely on the request’s correlation header staying the same.

PATCH /api/client/users HTTP/1.1
Host: apix.spotzee.com
Authorization: Bearer sk_…
Idempotency-Key: 1f6f4f7c-7a44-4cf6-9b3e-3b8a3a3b3a3a
Content-Type: application/json

[
  { "external_id": "user-9876", "email": "ada@example.com" }
]

Scope and TTL

Scope: keys are scoped per API key, so distinct API keys have separate replay caches. Within one API key, use a unique idempotency key across all paths and methods; changing the URL does not create a separate replay scope.
Per-surface scope: the Main API and Extended API maintain independent caches. The same Idempotency-Key sent to both surfaces is treated as two distinct requests. Pick a fresh key per surface if you want isolation, or reuse it deliberately knowing each surface will replay independently.
TTL: cached responses live for 24 hours. After that, a request with the same key runs as a brand-new operation.
Eligible methods: POST and PATCH. GET, HEAD, and DELETE are idempotent by definition and ignore the header.

What Spotzee does on replay

Replay scenario	Outcome
Same key, same body	Original response is returned. The `Idempotent-Replayed: true` response header confirms it’s a replay.
Same key, different body	`409 idempotency_key_mismatch`. Keys are tied to the exact request body. Use a fresh key for distinct requests.
Same key, in-flight (Main API)	`409 idempotency_in_progress` with `Retry-After`. The original request is still running; retry shortly.
Same key, in-flight (Extended API)	The duplicate runs and is cached on completion. There is no in-flight 409 on this surface. Successive replays after the first response lands return the cached copy.

Errors

{
  "status": "error",
  "code": "idempotency_key_mismatch",
  "title": "Idempotency key mismatch",
  "message": "The Idempotency-Key was reused with a different request body. Use a fresh key for distinct requests.",
  "type": "https://spotzee.com/docs/main-api/errors#idempotency_key_mismatch",
  "request_id": "req_01HXY…"
}

HTTP	`code`	When
`400`	`idempotency_key_invalid`	Invalid Main API key when enforcement is enabled: whitespace-only or longer than 255 characters
`400`	`parameter_invalid_format`	Invalid Extended API key: whitespace-only or longer than 255 characters
`409`	`idempotency_key_mismatch`	Same key reused with a different body
`409`	`idempotency_in_progress`	Original request still running. Retry after `Retry-After`. Main API only (once enforcement ships).

Generating keys

Use a non-empty opaque string of up to 255 characters. Pick a generator that suits your platform:

crypto.randomUUID()

import uuid
str(uuid.uuid4())

import "github.com/google/uuid"
uuid.NewString()

When not to reuse a key

Reuse a key for the same logical operation. For example, retrying the same contact upsert after a timeout. Mint a fresh key when:

The user submits the form a second time after deciding to change a field.
You’re processing a queue and each message is a distinct operation.
You’re running a backfill. Each row is its own logical request.

Caching rules

2xx responses are cached.
4xx responses are eligible for caching except 408, 425, and 429.
5xx, 408, 425, and 429 responses are not cached so retries can succeed when the platform recovers.
Oversized or unreadable response bodies are not cached. The Main API also excludes responses carrying Retry-After.

Next steps

Rate limits

Request limits and retry headers.

Errors

Status codes and the code catalogue.

Get started

Build

Configure

SDKs

Integrate

Reporting

Tools

API conventions

Recipes

How it works

Scope and TTL

What Spotzee does on replay

Errors

Generating keys

When not to reuse a key

Caching rules

Next steps

Rate limits

Errors

​How it works

​Scope and TTL

​What Spotzee does on replay

​Errors

​Generating keys

​When not to reuse a key

​Caching rules

​Next steps

Rate limits

Errors

How it works

Scope and TTL

What Spotzee does on replay

Errors

Generating keys

When not to reuse a key

Caching rules

Next steps