Skip to main content
Network blips, timeouts, and double-taps happen. To make retries safe, send an Idempotency-Key header on the billable, resource-creating POST endpoints. If the same key arrives again, Swippee replays the original response instead of doing the work twice — so a retry can’t create a duplicate report or charge your quota twice.
Use any unique, hard-to-guess value (a UUID v4 is ideal). Generate it once per logical operation and reuse it across that operation’s retries — not per HTTP attempt.

​
Where it applies

Other write endpoints (e.g. POST /v1/decisions) are already idempotent by a natural key, so a key is optional there. GET requests never need one.

​
Behaviour

  • First request — processed normally; the response is cached against your key.
  • Retry (same key, same params) — the original response is replayed verbatim, with an Idempotent-Replayed: true header. No new report, no extra charge.
  • Still in flight — if a retry arrives while the first is still processing, you get 409 IDEMPOTENCY_IN_PROGRESS. Wait a moment and retry the same key.
  • Key reused with different params — 422 IDEMPOTENCY_KEY_REUSED. A given key is bound to its first request body; use a fresh key for a new request.
  • Server error (5xx) — the key is released so your retry can reprocess. Only deterministic responses (success and client errors) are cached.

​
Scope & lifetime

  • Keys are scoped to your organization and environment (live vs test keys never collide).
  • Cached responses expire after 24 hours — retries beyond that window are treated as new requests.
  • Keys must be 8–255 characters.