Idempotency

Network failures, mobile timeouts, and aggressive proxies all create a familiar problem: did the request succeed? If you retry, you risk a duplicate. If you don’t, you risk losing data.

Nordva Launch solves this with the Idempotency-Key header. Provide a unique key per logical operation; replays within 24 hours return the original response unchanged.

Usage

curl -X POST https://api.nordva.dev/v1/waitlist/signups \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: f4c1a3d0-7e2b-4d3c-9f17-83b1f04d2c1c" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

Retry with the same Idempotency-Key and the same body → you get the original response (status + body + headers), including the original request_id.

Rules

• Keys must be 1–80 characters, ASCII printable.
• We recommend UUIDv4. ULIDs and any opaque per-request ID also work.
• Scope is per API key — collisions across different keys are impossible.
• Retention: 24 hours from first request. After that the key may be reused.
• If you replay the same key with a different body, you get IDEMPOTENCY_CONFLICT (409). This catches bugs.

Which endpoints

All POST endpoints that create resources accept Idempotency-Key. GET, PATCH, and DELETE ignore it.

A pragmatic tip

If your client framework already generates a request ID, reuse it. The cheapest correct implementation looks like:

const key = crypto.randomUUID();
await fetch(url, {
  method: "POST",
  headers: { "Idempotency-Key": key, ...auth, ...json },
  body: JSON.stringify(payload),
});