Idempotency

Network failures don't tell you whether a write landed. Idempotency keys make retries safe: send the same key with the same request, and the API guarantees the operation runs at most once — a retry replays the first response instead of, say, creating a second invitation.

Sending a key

Pass any unique string (a UUID v4 is ideal) in the Idempotency-Key header:

curl -X POST https://gallery.example/api/v1/gallery/offers \
  -H "Authorization: Bearer gpk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4a3f2c9e-8b1d-4e5f-9c7a-2d6b8e0f1a3c" \
  -d '{ "contact_id": "…" }'

Generate one key per logical operation, and reuse that exact key for every retry of that operation. Don't reuse a key for a different request.

How it behaves

• First request — the operation runs; the response is stored against the key.
• Retry (same key, same endpoint) — the stored response is returned and the operation does not run again.
• Same key, different endpoint — reusing a key against a different method or path returns 409 with code conflict (error format).
• Replay window — keys are kept for 24 hours. After that, the same key is treated as a fresh request.
• Scoping — keys are namespaced per principal, so your keys can't collide with another integration's.

Where it applies

Every state-changing write honors the header — each operation lists its Idempotency-Key parameter on its page in the API reference.

• Required on POST /gallery/invitations and POST /org/invitations — omitting the header returns 400 invalid_request (an invitation email must never be sent twice).
• Deliberately absent from the handful of POSTs where replaying a stored response would be wrong: read-shaped calls (caption parsing), endpoints that mint short-lived signed URLs or onboarding links (upload URLs, invoice PDF rendering, Stripe Connect), and re-check triggers (domain verification). A retry of those should simply run again.
• Unrecognized headers are ignored everywhere else, so it's always safe to send one — a good client sends an Idempotency-Key on every write and retries with the same key.