Idempotency
How Postforge API writes use Idempotency-Key so a retry never applies a change twice.
Networks fail: a request can time out after Postforge already did the work. Send an
Idempotency-Key header with every write, and retry with the same key until you get an answer.
PUT /v1/profiles/0192f3a4-5b6c-7d8e-9f01-23456789abcd/consent/email
Idempotency-Key: 7f9c2b8e-3d41-4f0a-9a6e-2c1d5e8b4a10How it works
- A key is 1 to 255 characters; a UUID per logical change is the simplest choice.
- The first request runs. Its answer, success or refusal, is kept for 24 hours.
- A retry with the same key and the same request gets that answer back, with
Idempotent-Replayed: true, without running again. - While the first request is still running, a retry gets
409with codeidempotency_key_in_use: wait a moment and retry. A request that died stops blocking its key after 5 minutes. - The same key with a different request (another operation or body) gets
422with codeidempotency_key_reused. Use a new key for a new change. - If the request failed unexpectedly (a
5xx), the key is freed, so a retry runs again.
Keys are scoped to the workspace: every API key and person in it shares one set of keys, so use a fresh UUID per change and two integrations can never collide.
Where it doesn't apply
GET requests are safe to repeat and ignore the header. A few writes whose answer holds a secret
shown once (creating or rotating an API key) refuse it with code idempotency_key_not_supported,
because that answer can't be stored for a replay.
Records that come from outside (orders and customers from a store, webhooks) are also written once by their own natural keys, so a platform resending them never creates duplicates.