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 the writes that send an email a retry must never duplicate: POST /gallery/invitations, POST /gallery/invitations/{id}/resend, POST /gallery/artist-invitations, POST /gallery/artist-invitations/{id}/resend, and POST /org/invitations. Omitting the header returns 400 invalid_request.
• Deliberately absent from the handful of POSTs where replaying a stored response would be wrong: read-shaped calls that compute a result (caption parsing, document extraction, a suggested subject line, a drafted reply, a room preview), endpoints that mint short-lived signed URLs, tokens, or session links (upload URLs, PDF rendering, Stripe Connect, the terminal connection token, a payment-method setup session), 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.