Retries and idempotency

What is safe to retry, and what to do when the API asks you to wait.

Retry these

Status	Why	How
`409`	Another publish is in flight for this account.	Wait a few seconds and repeat.
`429`	Rate limit exceeded.	Wait for `Retry-After`, then repeat.
`500`	Unexpected failure on our side.	Exponential backoff, with a ceiling.
Timeout / connection reset	The outcome is unknown.	See below before repeating.

Never retry 400, 401, 402, 403, 404 or 422. They describe something about the request or the account that a second attempt will not change.

Rate limits

The limit is 1,000 requests per 10-minute sliding window, per token. Past it, the next hundred requests are queued — they succeed, slowly — and only beyond that do you get:

Honour the header. The window releases capacity one segment at a time, so retrying earlier is refused again and spends part of your next segment.

Two practical measures:

Split tokens. Limits are counted per token, so a separate token per integrated system means a burst in one does not slow the others.

Prefer fewer, larger pages. PageSize=100 costs one request where ten pages of 10 cost ten.

manual-reinvite-to-review enforces its own per-envelope cooldown and also answers 429. That one is not about your budget, and it stops at the first signer that trips it — some signers on the envelope may already have been mailed.

Publishing never charges twice

Publishing debits one envelope from the account balance, and the debit is recorded against the envelope. Repeating the call cannot charge the account again or start a second workflow.

Once an envelope is Published, a further publish is refused with 400 — publication is accepted only from Draft, Hold or PublishScheduled. That is what makes a retry after an ambiguous failure safe: either it publishes an envelope that was not published, or it tells you it already was.

It is also why 409 is safe: it means another request holds the publish lock for your account, not that a second workflow is starting.

When the outcome is unknown

A timeout or a dropped connection tells you nothing about whether the request was applied. Do not blind-retry a create.

Creating an envelope returns its id in the response. If you never received it, look before you leap: list the vault and match on your own reference. privateDescription is a good place to keep an idempotency key of your own, precisely for this.

Publishing is safe to repeat, as above.

Updating, cancelling, holding, renaming and moving are state assignments rather than increments, so repeating them converges on the same result. Remember that a PUT is a full replace — retrying with a body you have since trimmed will remove what you left out.

Download URLs expire in a minute

GET /documents/{id}/original, /signed and GET /envelopes/{id}/certificate return a presigned URL valid for one minute, and the URL is briefly cached, so it can reach you with less than that remaining.

Fetch the file immediately. Never store one of these URLs, put it in a queue, or hand it to a job that runs later — ask for a fresh one at the moment you need the bytes.

Webhooks

The same discipline applies in the other direction. Deliveries are retried, so your endpoint will occasionally see the same event twice, and order is not guaranteed.

Key handlers on envelope_id plus event_type, make them idempotent, and treat an event as a signal to re-read the envelope from the API rather than as the state itself.

Retries and idempotency

Retry these#

Rate limits#

Publishing never charges twice#

When the outcome is unknown#