Idempotent requests
Retry a write safely with the Idempotency-Key header, and know what each repeat returns.
Send an Idempotency-Key header with a write to make it safe to repeat. Polymorfa runs the write at most once per key and answers every repeat without running it again. Only the methods listed on this page accept the header; other methods ignore it.
curl https://api.polymorfa.com/messaging/support/messages/send \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Idempotency-Key: 5f0c2b8e-4f7a-4f5e-9d1b-1c2d3e4f5a6b" \
-H "Content-Type: application/json" \
-d '{"conversation":{"phoneNumber":"+15550001111"},"content":{"text":"Your order shipped."}}'The key#
- A key is 1 to 255 bytes of UTF-8. Polymorfa trims surrounding spaces.
- Use a new random value, such as a UUID, or an ID from your own system for each write, and send the same value when you repeat that write.
- A key is bound to your team, the project, the credential that sent it, the method, the route and the
Polymorfa-Version. The same key sent with another credential or API version is a different key. - Polymorfa compares each repeat with the first request: the path, the body and, for Messaging writes, the
Prefer: respond-asyncchoice. - Messaging writes and campaign lifecycle requests on both APIs keep a key for one hour. Other Platform metadata receipts keep their documented windows.
Methods marked Required below return 400 without the header.
Messaging writes #
Messages, reactions, edits, deletes, campaign actions and Graph template writes record the outcome of the first request, not its response body. A repeat with the same key returns:
| First request | Repeat returns |
|---|---|
| Finished, but exact replay data is unavailable | 503 idempotency_replay_unavailable. The retained receipt prevents another execution. |
Failed with a recorded server error, such as result_unknown | 503 idempotency_replay_unavailable when exact replay data is denied or missing. Only an available authorized exact replay returns the original status and code with Idempotent-Replayed: true. The write does not run again. |
| Still running | 409 idempotency_in_progress with Retry-After: 1. |
| Started, but its outcome was not recorded | 409 idempotency_outcome_unknown. The write does not run again during the one-hour window. |
Different path, body or Prefer: respond-async choice | 422 idempotency_conflict. Nothing runs. |
The first response remains authoritative. Opaque message and campaign response bodies are not retained by default. An available exact replay carries Idempotent-Replayed: true; denied or lost replay data leaves the completed or unknown receipt in place and never repeats the write. Only a refusal proven to precede execution leaves the same key available for another attempt. Keep the first response and reconcile events or the resource after an uncertain result.
A replay-unavailable response does not establish whether the first request succeeded or failed. Do not treat that 503 as proof that nothing happened.
Graph template writes return Meta's error object. The Polymorfa code is in the X-Polymorfa-Error-Code header.
Audience and recipient writes #
These writes store their result. A repeat with the same key and request returns 200 with Idempotent-Replayed: true and the stored result; it does not apply the write again.
- A repeat sent while the first request is still running waits for it, then returns its result.
- A failed first request leaves no record. A repeat with the same key runs the write.
- A different request with the same key returns
422idempotency_conflict. - Access is checked again on every repeat.
- A recipient append repeat returns the original counts, even after the campaign launched.
- If the audience from the first create request was deleted, a repeat returns
410resource_gone.
| Method | Request | Header |
|---|---|---|
| Add project campaign recipients | API Add project campaign recipients | Optional |
| Add campaign recipients | API Add campaign recipients | Optional |
| Create audience | API Create audience | Optional |
| Add audience members | API Add audience members | Optional |
Platform writes that require a key #
These Platform writes require the header. Polymorfa keeps a receipt with the result for 24 hours.
- A repeat with the same key and request returns the stored result and does not apply the write again. The response's
idempotencyobject hasreplayed: true, the key and the receipt'screatedAtandexpiresAt. - A different request with the same key returns
422idempotency_conflict. - A failed request leaves no receipt. A repeat with the same key runs the write.
- Creating a webhook and rotating its secret return the signing secret only once. A repeat returns
secret: nullandsecretAvailable: false. - Reusing a BanSafe incident key for another Number returns
422bansafe_incident_idempotency_scope_conflict.
Test events #
Triggering a test event uses the key differently. The same key and body produce the same event ID, and Polymorfa delivers that event once. A different body creates a new event instead of returning a conflict. The key is 1 to 255 visible ASCII characters, and the 24-hour rules above do not apply.
| Method | Request | Header |
|---|---|---|
| Trigger test event | API Trigger test event | Optional |