Status Contact support Open app
Developers/Guides

Idempotency

Creating POSTs accept an Idempotency-Key header so a retry after a timeout cannot create a second resource.

HTTP
POST /v1/templates
Authorization: Bearer pb_live_…
Idempotency-Key: crm-00123-welcome
Content-Type: application/json

{ "name": "Welcome", "productSpecificationId": "psp_…" }

Rules:

  • The key is 1 to 255 characters and scoped to your organisation and the endpoint; the same key on another endpoint is a different key.
  • A repeat with the same body replays the stored response, with the header Idempotent-Replayed: true.
  • The same key with another body answers 422 idempotency_key_reused.
  • While the first request is still running, a duplicate answers 409 idempotency_in_progress; retry after a moment.
  • A failed request releases the key, so the corrected retry runs.
  • Keys are kept for 24 hours.

Use a natural key when you have one, such as the CRM record id plus the event that triggered the call. The SDKs expose idempotencyKey() / idempotency_key() for a random one. Operations that accept the header carry the "Idempotency-Key" pill in the reference.