---
title: "Retries and Errors"
description: "Decide which SignatureAPI errors to retry, wait on or fix, back off on 429 and 5XX responses, and retry envelope creation without creating duplicates."
canonical: "https://signatureapi.com/docs/api/guides/how-to/retries-and-errors"
source: "https://signatureapi.com/docs/api/guides/how-to/retries-and-errors.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T17:35:44Z"
---

# 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.

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/errors) page describes the error body.

## Which Errors to Retry

| Group            | Responses                                                                                                                                                                                                                                                                                                                                                                               | What to do                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Retry            | `429`, any `5XX`, a timeout or a dropped connection                                                                                                                                                                                                                                                                                                                                     | Retry the same request with backoff.                                                                |
| Wait, then retry | [`deliverable-not-ready`](https://signatureapi.com/docs/v1/errors/deliverable-not-ready), [`envelope-not-completed`](https://signatureapi.com/docs/v1/errors/envelope-not-completed), [`cannot-cancel`](https://signatureapi.com/docs/v1/errors/cannot-cancel) while the envelope is `processing`, [`too-early-to-resend`](https://signatureapi.com/docs/v1/errors/too-early-to-resend) | The request is right but too early. Wait for the event or time the error names, then send it again. |
| Fix, then send   | Every other `4XX`, such as `400`, `401`, `403`, `404`, `413` and `422`                                                                                                                                                                                                                                                                                                                  | The 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](https://signatureapi.com/docs/api/rate-limiting#handling-rate-limits) 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](https://signatureapi.com/docs/api/resources/envelopes/topics) 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.

```javascript 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.
