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

```bash
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-async` choice.
- 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`](https://docs.polymorfa.com/api/errors#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`](https://docs.polymorfa.com/api/errors#idempotency-in-progress) with `Retry-After: 1`. |
| Started, but its outcome was not recorded | `409` [`idempotency_outcome_unknown`](https://docs.polymorfa.com/api/errors#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`](https://docs.polymorfa.com/api/errors#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.

| Method | Request | Header |
| --- | --- | --- |
| [Create message template](https://docs.polymorfa.com/api/graph/templates/create-message-template) | `POST /graph/whatsapp/{version}/{wabaId}/message_templates` | Optional |
| [Delete message template](https://docs.polymorfa.com/api/graph/templates/delete-message-template) | `DELETE /graph/whatsapp/{version}/{wabaId}/message_templates` | Optional |
| [Create project campaign](https://docs.polymorfa.com/api/campaigns/create-project-campaign) | `POST /messaging/projects/{projectSlug}/campaigns` | Optional |
| [Launch project campaign](https://docs.polymorfa.com/api/campaigns/launch-project-campaign) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/launch` | Optional |
| [Pause project campaign](https://docs.polymorfa.com/api/campaigns/pause-project-campaign) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/pause` | Optional |
| [Resume project campaign](https://docs.polymorfa.com/api/campaigns/resume-project-campaign) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/resume` | Optional |
| [Stop project campaign](https://docs.polymorfa.com/api/campaigns/stop-project-campaign) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/stop` | Optional |
| [Send project campaign test](https://docs.polymorfa.com/api/campaigns/send-project-campaign-test) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/test-send` | Optional |
| [Reschedule project campaign](https://docs.polymorfa.com/api/campaigns/reschedule-project-campaign) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/reschedule` | Optional |
| [Launch campaign](https://docs.polymorfa.com/api/campaigns/launch-campaign) | `POST /platform/campaigns/{campaignId}/launch` | Optional |
| [Pause campaign](https://docs.polymorfa.com/api/campaigns/pause-campaign) | `POST /platform/campaigns/{campaignId}/pause` | Optional |
| [Resume campaign](https://docs.polymorfa.com/api/campaigns/resume-campaign) | `POST /platform/campaigns/{campaignId}/resume` | Optional |
| [Stop campaign](https://docs.polymorfa.com/api/campaigns/stop-campaign) | `POST /platform/campaigns/{campaignId}/stop` | Optional |
| [Reschedule campaign](https://docs.polymorfa.com/api/campaigns/reschedule-campaign) | `POST /platform/campaigns/{campaignId}/reschedule` | Optional |
| [Test send campaign](https://docs.polymorfa.com/api/campaigns/test-send-campaign) | `POST /platform/campaigns/{campaignId}/test-send` | Optional |
| [React to channel message](https://docs.polymorfa.com/api/channels/react-to-channel-message) | `POST /messaging/{session}/channels/{id}/messages/{messageId}/reaction` | Optional |
| [Send message](https://docs.polymorfa.com/api/messages/send-message) | `POST /messaging/{session}/messages/send` | Optional |
| [Send reaction](https://docs.polymorfa.com/api/messages/send-reaction) | `POST /messaging/{session}/messages/react` | Optional |
| [Edit message](https://docs.polymorfa.com/api/chats/edit-message) | `PUT /messaging/{session}/chats/{conversation}/messages/{messageId}` | Optional |
| [Delete message](https://docs.polymorfa.com/api/chats/delete-message) | `DELETE /messaging/{session}/chats/{conversation}/messages/{messageId}` | Optional |

## 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 `422` [`idempotency_conflict`](https://docs.polymorfa.com/api/errors#idempotency-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
  `410` [`resource_gone`](https://docs.polymorfa.com/api/errors#resource-gone).

| Method | Request | Header |
| --- | --- | --- |
| [Add project campaign recipients](https://docs.polymorfa.com/api/campaigns/add-project-campaign-recipients) | `POST /messaging/projects/{projectSlug}/campaigns/{id}/recipients` | Optional |
| [Add campaign recipients](https://docs.polymorfa.com/api/campaigns/add-campaign-recipients) | `POST /platform/campaigns/{campaignId}/recipients` | Optional |
| [Create audience](https://docs.polymorfa.com/api/audiences/create-audience) | `POST /platform/audiences` | Optional |
| [Add audience members](https://docs.polymorfa.com/api/audiences/add-audience-members) | `POST /platform/audiences/{listId}/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 `idempotency` object has
  `replayed: true`, the key and the receipt's `createdAt` and `expiresAt`.
- A different request with the same key returns `422`
  [`idempotency_conflict`](https://docs.polymorfa.com/api/errors#idempotency-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: null` and `secretAvailable: false`.
- Reusing a BanSafe incident key for another Number returns `422`
  [`bansafe_incident_idempotency_scope_conflict`](https://docs.polymorfa.com/api/errors#bansafe-and-safe-mode-codes).

| Method | Request | Header |
| --- | --- | --- |
| [Create team webhook](https://docs.polymorfa.com/api/webhook-endpoints/create-team-webhook) | `POST /platform/webhooks` | Required |
| [Update team webhook](https://docs.polymorfa.com/api/webhook-endpoints/update-team-webhook) | `PATCH /platform/webhooks/{webhookId}` | Required |
| [Delete team webhook](https://docs.polymorfa.com/api/webhook-endpoints/delete-team-webhook) | `DELETE /platform/webhooks/{webhookId}` | Required |
| [Rotate team webhook secret](https://docs.polymorfa.com/api/webhook-endpoints/rotate-team-webhook-secret) | `POST /platform/webhooks/{webhookId}/secret-rotations` | Required |
| [Test team webhook](https://docs.polymorfa.com/api/webhook-endpoints/test-team-webhook) | `POST /platform/webhooks/{webhookId}/tests` | Required |
| [Create project webhook](https://docs.polymorfa.com/api/webhook-endpoints/create-project-webhook) | `POST /platform/projects/{projectId}/webhooks` | Required |
| [Update project webhook](https://docs.polymorfa.com/api/webhook-endpoints/update-project-webhook) | `PATCH /platform/projects/{projectId}/webhooks/{webhookId}` | Required |
| [Delete project webhook](https://docs.polymorfa.com/api/webhook-endpoints/delete-project-webhook) | `DELETE /platform/projects/{projectId}/webhooks/{webhookId}` | Required |
| [Rotate project webhook secret](https://docs.polymorfa.com/api/webhook-endpoints/rotate-project-webhook-secret) | `POST /platform/projects/{projectId}/webhooks/{webhookId}/secret-rotations` | Required |
| [Test project webhook](https://docs.polymorfa.com/api/webhook-endpoints/test-project-webhook) | `POST /platform/projects/{projectId}/webhooks/{webhookId}/tests` | Required |
| [Cancel operation](https://docs.polymorfa.com/api/operations/cancel-operation) | `POST /platform/operations/{operationId}/cancel` | Required |
| [Cancel project operation](https://docs.polymorfa.com/api/operations/cancel-project-operation) | `POST /platform/projects/{projectId}/operations/{operationId}/cancel` | Required |
| [Create BanSafe incident](https://docs.polymorfa.com/api/bansafe/create-ban-safe-incident) | `POST /platform/bansafe/incidents` | Required |
| [Replay team event](https://docs.polymorfa.com/api/events/replay-team-event) | `POST /platform/events/{eventId}/replays` | Required |
| [Replay project event](https://docs.polymorfa.com/api/events/replay-project-event) | `POST /platform/projects/{projectId}/events/{eventId}/replays` | Required |
| [Retry team webhook delivery](https://docs.polymorfa.com/api/webhook-deliveries/retry-team-webhook-delivery) | `POST /platform/webhook-deliveries/{deliveryId}/retry` | Required |
| [Retry project webhook delivery](https://docs.polymorfa.com/api/webhook-deliveries/retry-project-webhook-delivery) | `POST /platform/projects/{projectId}/webhook-deliveries/{deliveryId}/retry` | Required |
| [Enable customers](https://docs.polymorfa.com/api/customers/enable-customers) | `POST /platform/projects/{projectId}/customers/enable` | Required |
| [Create customer](https://docs.polymorfa.com/api/customers/create-customer) | `POST /platform/customers` | Required |
| [Archive customer](https://docs.polymorfa.com/api/customers/archive-customer) | `POST /platform/customers/{customerId}/archive` | Required |
| [Restore customer](https://docs.polymorfa.com/api/customers/restore-customer) | `POST /platform/customers/{customerId}/restore` | Required |
| [Create customer pairing link](https://docs.polymorfa.com/api/customers/create-customer-pairing-link) | `POST /platform/customers/{customerId}/pairing-links` | Required |
| [Transfer customer number](https://docs.polymorfa.com/api/customers/transfer-customer-number) | `POST /platform/customers/{customerId}/numbers/{sessionId}/transfer` | Required |

## 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](https://docs.polymorfa.com/api/testing/trigger-test-event) | `POST /messaging/{session}/test-events` | Optional |

## See also

- [Retry writes safely](https://docs.polymorfa.com/development/idempotency)
- [Handle errors](https://docs.polymorfa.com/development/error-handling)
- [Errors](https://docs.polymorfa.com/api/errors)
