Idempotency & retries

Networks fail: a request can time out after the API processed it. Here is what is safe to retry today.

No Idempotency-Key header

The API does not support a generic Idempotency-Key header. Idempotency is built into specific operations, listed below. Other POST requests may create a duplicate if you retry them blindly.

Safe to retry

Operation	Why
Every GET	Read only.
PATCH, PUT updates	Setting the same values twice gives the same result.
DELETE	A second call answers 404 (already deleted).
POST /v1/registered-mails/{id}/send	Idempotent by the idempotencyKey field (see below).
Provisioning POST with an externalId	Returns the existing resource with 200 and created: false. See Partner provisioning.
POST /v1/oauth/grants/exchange	Single use: a second call answers 422 invalid_grant, the first one already confirmed the grant.

Sending registered mail

Sending takes a mandatory idempotencyKey (8 to 128 characters): generate one per sending (a UUID is fine) and reuse it on every retry.

POST /v1/registered-mails/0192f3a1-7c2e-7b4d-9a61-500000000001/send
{ "idempotencyKey": "5f1c2b9e-8f0a-4c7d-9d3e-2a6b1c0e9f47" }

• Same key again: the API returns the current state of the mail, without sending anything.
• Another key on a mail already sent: 409 registered_mail_already_sent.

Creation requests

POST /v1/signature-requests, POST /v1/contacts, POST /v1/tasks and POST /v1/registered-mails (draft) are not idempotent. After a timeout:

1. Look for the resource before retrying: list recent signature requests of the entity, or search contacts with q / GET /v1/contacts/duplicates.
2. Store your own identifier on the resource when the schema has one (externalRef on contacts, clientReference on registered mail) to find it again.

Webhooks

Deliveries are at least once: the same event can reach you more than once (retries, manual replays). Deduplicate on the event id (also in the X-MLT-Event-Id header), which never changes across retries and replays. See Webhooks.

Retry strategy

• Retry 429 after Retry-After seconds, and 5xx / network errors with exponential backoff (e.g. 1 s, 2 s, 4 s, then give up and alert).
• Never retry 400, 403, 404, 409 or 422 unchanged.
• Retry 401 invalid_token once with a fresh token.