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. 
curl -X POST https://api.swippee.com/v1/parse \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -F "file=@statement.pdf"
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

EndpointWhy
POST /v1/parseEach call creates a report and consumes parse quota.
POST /v1/verify/issueEach call mints a new verification token.
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.