Skip to content

Build and test

Retries and Errors

Decide which SignatureAPI errors to retry, wait on or fix, back off on 429 and 5XX responses, and retry envelope creation without creating duplicates.

Every failed request falls into one of three groups. Read the HTTP status first and the problem type second; don’t parse detail, because its wording can change. The Errors page describes the error body.

Which Errors to Retry

GroupResponsesWhat to do
Retry429, any 5XX, a timeout or a dropped connectionRetry the same request with backoff.
Wait, then retrydeliverable-not-ready, envelope-not-completed, cannot-cancel while the envelope is processing, too-early-to-resendThe request is right but too early. Wait for the event or time the error names, then send it again.
Fix, then sendEvery other 4XX, such as 400, 401, 403, 404, 413 and 422The request fails again unchanged. Fix the cause named in detail or errors.

For a “wait” error, an event usually tells you when to try again: deliverable.generated for a deliverable, envelope.completed before you create a deliverable, and envelope.started before you cancel. Prefer reacting to the event over polling.

Back Off Between Attempts

Wait 1 second before the first retry and double the wait after each failure. Stop after 5 retries and log the request for investigation. API-key responses carry no Retry-After header, so the schedule is up to you.

Rate Limiting has the full schedule and a retry helper in Node.js and Python. The same helper works for 5XX responses if you add them to its retry condition.

Retry Envelope Creation Without Duplicates

POST /v1/envelopes creates a new envelope on every call. If a request times out, the envelope may exist anyway, and a blind retry creates a second one. Your recipients then get a second signing request.

Look before you retry. Give each envelope a topic built from your own record, such as order_1001, and check for it before each attempt:

  1. Before each attempt, list envelopes with GET /v1/envelopes?topic=order_1001&limit=1.
  2. If the list has an envelope, the earlier attempt worked: use it.
  3. Otherwise, create the envelope with that topic in topics.
  4. On a 429, a 5XX or a timeout, wait and go back to step 1.
Node.js
const API = "https://api.signatureapi.com/v1";
const headers = { "X-API-Key": process.env.SIGNATUREAPI_KEY, "Content-Type": "application/json" };

// Creates at most one envelope per order, even when a request times out.
export async function createEnvelopeOnce(orderId, envelope) {
  const topic = `order_${orderId}`;
  for (let attempt = 1; attempt <= 5; attempt++) {
    // Did an earlier attempt create it? Look it up by its topic first.
    const found = await fetch(`${API}/envelopes?topic=${topic}&limit=1`, { headers });
    if (found.ok) {
      const { data } = await found.json();
      if (data.length > 0) return data[0];
    }
    try {
      const res = await fetch(`${API}/envelopes`, {
        method: "POST",
        headers,
        body: JSON.stringify({ ...envelope, topics: [topic] }),
        signal: AbortSignal.timeout(30_000),
      });
      if (res.status === 201) return res.json();
      if (res.status !== 429 && res.status < 500) {
        throw new Error(`${res.status}: ${await res.text()}`); // fix the request, don't retry
      }
    } catch (error) {
      if (error.name !== "TimeoutError" && error.name !== "TypeError") throw error;
    }
    await new Promise((resolve) => setTimeout(resolve, 2 ** (attempt - 1) * 1000));
  }
  throw new Error(`Could not create the envelope for order ${orderId}`);
}

Topics must start with a lowercase letter and contain only lowercase letters, digits and underscores, up to 32 characters. An envelope holds up to 10 topics, so this one still leaves room for the topics you filter webhooks by.

Log What You Need

When a request fails for good, log the method, the path, the status, the problem type and detail (or errors), and the envelope or recipient ID. Never log the API key.