Idempotency

Safe retries, replay semantics, conflict behaviour and key retention.

Use the optional Idempotency-Key header, or _idempotency_key for HTML forms, to make retries safe.

Rules

  • Maximum 128 characters.
  • Scoped to the form, not the endpoint.
  • If both the header and field are supplied, their values must match.
  • Generate one key per logical submission and reuse it while the payload is unchanged.
  • Rotate the key after success or when the payload changes.

Replay

An identical request with the same key and equivalent payload returns:

HTTP/1.1 200 OK
{
  "success": true,
  "submission_id": "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60",
  "message": "Your enquiry has been received."
}

No new submission, delivery or notification is created. Replays are returned after origin and rate-limit checks but before Turnstile verification, so a lost response can be retried without consuming another single-use token.

Conflicting payloads

Reusing a key with different content returns 409 idempotency_conflict:

{
  "success": false,
  "error": {
    "code": "idempotency_conflict",
    "message": "This idempotency key was already used with different content."
  },
  "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
}

The original submission is not changed and no notification is sent.

Equivalence

Payloads are compared after:

  • removing reserved control fields;
  • canonicalising object key order;
  • recursively preserving list order.

Turnstile and honeypot values are excluded from the digest.

Retention

The key is stored on the submission and retained for the form’s retention period (default 90 days, maximum 365 days). The scheduled retention purge removes it. After purge, reusing an old key may create a new submission, so always generate unique keys.

See Preventing duplicate submissions.