Skip to main content
Every refusal the API returns deliberately, at every status, is { "error": { "code", "message" } }, and such a response is a failure if and only if it carries an error key — that test is right even for a client that ignores the status line. An unexpected server failure may not have this shape: treat a 5xx without an error key as an internal_error, which is retryable. code is the contract and never changes meaning or spelling; message is prose for a log and may be reworded. The enum is closed, so a switch over it can be total and needs no default branch that means “something we did not publish”. Each code says whether retrying the identical request could ever succeed, and how to wait if so. The same table is at the root of the OpenAPI document as x-error-codes.

Retrying a request safely

These operations require an Idempotency-Key: A DELETE takes no key, because repeating one cannot do anything twice. A retry of a DELETE /api/v1/envelopes/{envelopeId} or a DELETE /api/v1/webhooks/{webhookId} whose first attempt took effect is answered not_found: the thing is already gone. The key identifies one request, not one envelope: generate a key for each request you intend, store it before the first attempt, and reuse it only to retry that same request with the identical body. Creating a draft and then sending it are separate requests, each with its own key; a key already used for one is refused for the other as idempotency_key_reused, and so is the same key with a different body. A retry while the first attempt is still running is answered request_in_progress: retry the identical request under the backoff the table above gives for that code. Within the key’s retention window, which the create-envelope reference states, a retry returns the first attempt’s answer and does nothing again. Past the window the key can be forgotten at any time, and a request carrying it is then a new request:
  • A send that already went out is refused as envelope_not_draft, and a void that already took effect is refused as envelope_not_sent. A late retry of either changes nothing.
  • A late retry of a request that creates something is not harmless: it can create it again — a second template, envelope or batch, and an envelope that is sent emails its recipients again.
So past the window, stop and find out whether the first attempt created something before creating anything:
  • For a template, the template list is newest first and each row carries id, name and created_at. Look for one created around your first attempt under the name it was given.
  • For an envelope, set reference on every envelope you create — on POST /api/v1/envelopes, on a one-off, and on each row of a batch — and store it before the first attempt, beside the idempotency key. Past the window, ask the envelope list with ?reference= and the value you sent. A row means the first attempt created that envelope; an empty page means it did not. The reference is compared in Unicode NFC whichever form you send, and it cannot be changed after creation, so it still names the envelope when you come back for it.
  • The API does not make a reference unique: it accepts one value on any number of envelopes, and the list returns every match, newest first. For exactly one envelope per reference, derive it from the record in your system that asked for the envelope — not from the attempt — and never reuse it.
  • Each row carries id, title, status, template_id, reference, created_at and sent_at — no recipients. ?reference= combines with status and cursor.
  • For an envelope created without a reference, the list cannot be searched by your own identifiers. Narrow it to rows with the template_id you sent (null for a one-off) created around your first attempt, read each candidate with GET /api/v1/envelopes/{envelopeId}, and match its recipients on the email and the external_ref you sent. external_ref is stored NFC-normalised, so normalise your own value to NFC before comparing.