Skip to content
Developers Dashboard

GuidesConventions

Idempotency

A network error doesn’t tell you whether the envelope was made. Send an Idempotency-Key with POST /v1/envelopes and you can retry safely: you’ll never get two envelopes for one key.

How it works

  • Use any string up to 64 characters that’s unique to the envelope you mean — an order number or a UUID. Longer is 400 invalid_idempotency_key.
  • It works with and without template_id, and with send: true.
  • Repeat the call with the same key and the same body, and you get the envelope made the first time, as it is now: 200 (not 201) and the header Idempotent-Replayed: true. Nothing is created or sent again.
  • The same key with a different body is 409 idempotency_key_reused — the key belongs to the first request. A key used by the other mode (live or test) is refused the same way.
  • The body is compared as data, so spacing and key order don’t matter.
  • A key stays used as long as its envelope exists, Trash included. A call that fails leaves no envelope behind, so retrying it with the same key starts clean.
POST /v1/envelopes
Idempotency-Key: lease-1042

HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replayed: true
SignAnything-Request-Id: req_3a9e5c1f7b2d4a8e6c0f2b9d

{ "id": "env_4f9c2d7e1b8a4c6f9e2d3b7a1c5e8f02", "object": "envelope", "status": "sent", "…": "…" }

Other calls

Only POST /v1/envelopes takes an Idempotency-Key. Reads, PATCH and DELETE are safe to repeat as they are. For other POSTs, check before retrying: a repeated send answers 409 already_sent, a repeated void 409 not_voidable.