Idempotency

​

How it works

PATCH /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 you can reuse the same key string across keys without collision.
• 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

​

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…"
}

​

Generating keys

crypto.randomUUID()

import uuid
str(uuid.uuid4())

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

​

When not to reuse a key

• 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 cached (your retry would have failed the same way).
• 5xx and 429 responses are not cached so retries can succeed when the platform recovers.

​

Next steps