Idempotency
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.