Skip to content
  1. Blog
  2. Learning

API Retry Mechanism: What It Is and How It Works

TL;DR: An API retry mechanism sends a failed request again after a short, growing wait, but only for errors that are likely to pass. Retry logic that works well uses capped exponential backoff with jitter, a time limit, the Retry-After header and idempotency keys. Our eSignature API page shows the kind of API you can practice these retries against.

Your app calls an API, and the call fails. Maybe the network dropped for a second, or the service told you to slow down. Should your code try again, and how soon?

This guide explains how to retry safely. It covers which errors to retry, how long to wait, and how to stop retries from making an outage worse. Code samples in Node.js, Python and C# show each idea in practice.

What is an API retry mechanism?

An API retry mechanism is code that sends a failed API request again, following a set of rules. Those rules decide which failures to retry, how long to wait and when to give up.

Think of calling a friend whose line is busy. You wait a minute and call again, then wait a little longer. You do not redial every two seconds, and after a few tries you send a text instead.

Retries work the same way. Retry logic does the calling, and a retry policy holds the rules. Together they form the retry mechanism.

What does a retry policy include?

A retry policy has four parts. Each one answers a simple question about the next retry attempt.

  • Which errors to retry: temporary failures only, such as time-outs and overloaded servers.
  • Attempt limit: how many tries in total, counting the first one.
  • Backoff: the retry delay between attempts, which usually grows each time.
  • Jitter: a little randomness in each delay so clients do not retry together.

Most cloud software development kits (SDKs) include these parts already. The Amazon Web Services (AWS) guide to SDK retry behavior describes a standard mode that uses jittered exponential backoff.

Which errors should you retry?

Retry API calls that fail with errors likely to pass on their own. Fail fast on errors that will come back every time, because each extra try only adds load.

Which errors are usually safe to retry?

  • Network blips: dropped connections, Domain Name System (DNS) hiccups and lost packets.
  • Time-outs, when the operation is safe to repeat.
  • Rate limits, such as a Hypertext Transfer Protocol (HTTP) 429 response.
  • Short overloads or maintenance, such as an HTTP 503 response.
  • Calls through gRPC Remote Procedure Calls (gRPC) that fail with UNAVAILABLE, if your policy allows it.

Which errors should fail fast?

  • Most 400-range client errors, such as a bad sign-in, a missing record or invalid data.
  • Operations that create something, like a payment, unless you add an idempotency key.
  • Any call to a service that is already overloaded, since retries add to the load.

How does a retry mechanism work from start to finish?

A retry mechanism checks each failure, waits and tries again until the call works or a limit is reached. The diagram shows that loop.

Flow diagram of an API retry mechanism: send the request, check whether the error is retryable, wait with backoff and jitter, then retry or stop

  1. Send the request with a time-out for this attempt.
  2. Return the response when it succeeds or fails with an error you should not retry.
  3. Work out the delay from backoff and jitter, or from the Retry-After header.
  4. Stop when you reach the attempt limit or the total time limit.
  5. Otherwise, wait for the delay and send the request again.

A bounded retry always has these stop conditions. Without bounded retries, one failing call can run forever.

How do fixed, linear and exponential backoff compare?

Exponential backoff is the usual default, because the wait grows fast and gives a struggling service room to recover. Fixed and linear delays are simpler but space retries out less.

Strategy Delay pattern Trade-off
Fixed interval 1s, 1s, 1s Simple, but clients can hit the service together
Linear backoff 1s, 2s, 3s Better spacing, still predictable
Exponential backoff Doubles each time, up to a cap Common default, especially with jitter

Here is API backoff in numbers. With a base of 0.2 seconds, the delays run 0.2, 0.4, 0.8, 1.6 and 3.2 seconds. A 10-second cap stops the delay from growing past that point.

How does jitter prevent retry storms?

Jitter adds a random amount to each delay so clients spread their retries out. Without it, clients that failed together compute the same delay and all retry at the same moment.

That crowd of matching retries is often called a thundering herd. The AWS article on exponential backoff and jitter compares three common ways to add randomness:

  • Full jitter: sleep = random(0, base * 2^attempt)
  • Equal jitter: sleep = (base * 2^attempt)/2 + random(0, (base * 2^attempt)/2)
  • Decorrelated jitter: sleep = min(cap, random(base, prev_sleep * 3))

Full jitter is the simplest to read, and the code samples later in this post use it.

What retry limits and time limits should you set?

Start with three to five attempts and a total time limit that matches how long your user can wait. Then tune the numbers against real traffic.

  • Max attempts: 3 to 5, including the first try.
  • Time-out per attempt: short and steady, such as 1 to 5 seconds.
  • Max delay between attempts: 10 to 30 seconds.
  • Total retry time: 10 to 60 seconds, set by your service level objective (SLO).

Configure the standard retry mode when your cloud SDK already has one, rather than writing your own. Retry-After overrides your own delay when a service tells you to retry later.

Your API provider’s limits matter too. The BoldSign API rate limit is 2,000 requests per hour in production and 50 per hour in the sandbox. Both limits apply per account, not per app or user.

Why do safe retries need idempotency?

A retry is safe only when repeating the request has the same effect as sending it once. That property is called idempotency.

Which HTTP methods are idempotent?

GET, PUT and DELETE are idempotent by design, so a repeat changes nothing. POST usually creates something new, so a retried POST can create a duplicate.

How do you make a POST request safe to retry?

  • Send an idempotency key with requests such as “create order” or “charge card”.
  • Have the server store the key and return the first result for any repeat.
  • Use PUT with an ID your client creates, when the API allows it.

The Google Cloud retry strategy guide ties each retry decision to whether the operation is idempotent.

Where should retries live: client, gateway, server or worker?

Put retries in one main layer, usually the client or a background worker. Retries stacked in every layer multiply traffic during an incident.

Client-side retries

Most retry requests start in the client. It sits closest to the failure and hides short network faults from your users. Badly tuned clients can still multiply load, because there are many of them.

API gateway retries

A gateway applies one retry policy for every service behind it. The catch is that clients may never learn about the failures it hides. Ask what types of solutions handle adaptive timeouts and retry strategies at the API router, since a gateway does exactly that job.

Service-to-service retries

Retries between your own microservices work when you control both sides. During an incident, they can multiply load deep inside the system, so give each service a small retry budget.

Queue and worker retries

Background jobs, event processing and long-running workflows suit retries well. A worker can wait without keeping a user on hold. Workers need idempotent handlers and a dead-letter queue (DLQ) for messages that keep failing.

How do retries differ for web APIs, gRPC and message queues?

Each system means something slightly different by a retry. The table shows what you configure in each one and the mistake to watch for.

Most web APIs follow Representational State Transfer (REST), so a retry there resends an HTTP request.

System What a retry means What you configure Watch out for
REST over HTTP Send the HTTP request again Retryable status codes, deadline, idempotency, Retry-After Retrying a POST that is not idempotent
gRPC Repeat the call from the client channel Retry policy: max attempts, backoff, retryable status codes Assuming every failure is retried by default
Message queues Deliver the message again or rerun the handler Delivery count, visibility time-out, backoff, DLQ A bad message looping forever

The gRPC retry guide explains that gRPC retries only a few cases on its own. Set an explicit retry policy for anything more.

How do you implement REST retries in Node.js with exponential backoff and jitter?

The function below wraps fetch. It retries idempotent methods with full jitter and honors the Retry-After header.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
function isRetryableHttpStatus(status) {
  // Typical retriable server-side/transient codes.
  return status === 429 || status === 503 || (status >= 500 && status <= 599);
}
function parseRetryAfterSeconds(headers) {
  // Retry-After can be seconds or an HTTP-date; keep it simple here.
  const v = headers.get("retry-after");
  if (!v) return null;
  const n = Number(v);
  return Number.isFinite(n) ? n : null;
}
function fullJitterDelayMs(baseMs, capMs, attempt) {
  const exp = Math.min(capMs, baseMs * 2 ** attempt);
  return Math.floor(Math.random() * exp); // full jitter
}
export async function fetchWithRetry(url, options = {}) {
  const {
    maxAttempts = 4, // includes the first attempt
    baseDelayMs = 200,
    capDelayMs = 10_000,
    perAttemptTimeoutMs = 5_000,
    signal,
    retryOnMethods = new Set(["GET", "PUT", "DELETE", "HEAD", "OPTIONS"]),
  } = options.retry ?? {};
  const method = (options.method ?? "GET").toUpperCase();
  // Guardrail: don't blindly retry non-idempotent methods.
  if (!retryOnMethods.has(method)) {
    return fetch(url, { ...options, signal });
  }
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), perAttemptTimeoutMs);
    try {
      const res = await fetch(url, {
        ...options,
        signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal,
      });
      if (!isRetryableHttpStatus(res.status)) return res;
      // Honor Retry-After when present (common with 429/503).
      const ra = parseRetryAfterSeconds(res.headers);
      const delayMs =
        ra != null
          ? Math.min(capDelayMs, ra * 1000)
          : fullJitterDelayMs(baseDelayMs, capDelayMs, attempt);
      if (attempt === maxAttempts - 1) return res; // last attempt, return response
      await sleep(delayMs);
      continue;
    } catch (err) {
      // Network error / timeout: retry with backoff, unless last attempt.
      if (attempt === maxAttempts - 1) throw err;
      const delayMs = fullJitterDelayMs(baseDelayMs, capDelayMs, attempt);
      await sleep(delayMs);
    } finally {
      clearTimeout(timeout);
    }
  }
}

Why this works in production:

  • Attempts are bounded, and each one has its own time-out.
  • Jitter keeps clients from retrying in step.
  • Retry-After is honored for 429 and 503 responses.
  • Only idempotent methods are retried by default.

How do you implement retries in Python for requests-based clients?

This version uses a plain loop, with no extra packages. It uses capped exponential backoff and full jitter, like the Node.js sample.

import random
import time
import requests

RETRYABLE_STATUS = {429, 503}  # plus most 5xx
RETRYABLE_5XX_MIN = 500
RETRYABLE_5XX_MAX = 599


def is_retryable_status(code: int) -> bool:
    return code in RETRYABLE_STATUS or (RETRYABLE_5XX_MIN <= code <= RETRYABLE_5XX_MAX)


def full_jitter_delay(base: float, cap: float, attempt: int) -> float:
    exp = min(cap, base * (2**attempt))
    return random.random() * exp  # full jitter


def request_with_retry(
    method: str,
    url: str,
    *,
    max_attempts: int = 4,
    base_delay_s: float = 0.2,
    cap_delay_s: float = 10.0,
    timeout_s: float = 5.0,
    session: requests.Session | None = None,
    **kwargs,
) -> requests.Response:
    m = method.upper()
    if m not in {"GET", "PUT", "DELETE", "HEAD", "OPTIONS"}:
        # Guardrail: don't blindly retry non-idempotent methods
        return (session or requests).request(m, url, timeout=timeout_s, **kwargs)
    s = session or requests.Session()
    for attempt in range(max_attempts):
        try:
            resp = s.request(m, url, timeout=timeout_s, **kwargs)
            if not is_retryable_status(resp.status_code):
                return resp
            # Basic Retry-After handling (seconds only)
            ra = resp.headers.get("Retry-After")
            if ra and ra.isdigit():
                delay = min(cap_delay_s, float(ra))
            else:
                delay = full_jitter_delay(base_delay_s, cap_delay_s, attempt)
            if attempt == max_attempts - 1:
                return resp
            time.sleep(delay)
        except (requests.Timeout, requests.ConnectionError):
            if attempt == max_attempts - 1:
                raise
            delay = full_jitter_delay(base_delay_s, cap_delay_s, attempt)
            time.sleep(delay)
    raise RuntimeError("Unreachable")

How do you implement retries in C# with HttpClient and Polly?

Polly is a common library for retry policies around HttpClient in C#. The policy below retries server errors, 429 and 503 three times with full jitter.

// Install-Package Polly
// Install-Package Polly.Extensions.Http
using Polly;
using Polly.Extensions.Http;
using System.Net;
using System.Net.Http.Headers;
static IAsyncPolicy BuildRetryPolicy()
{
    return HttpPolicyExtensions
        .HandleTransientHttpError() // 5xx + network errors
        .OrResult(msg => msg.StatusCode == (HttpStatusCode)429 || msg.StatusCode == HttpStatusCode.ServiceUnavailable)
        .WaitAndRetryAsync(
            retryCount: 3,
            sleepDurationProvider: attempt =>
            {
                // Full jitter: random(0..base*2^attempt), cap separately if needed
                var baseMs = 200 * Math.Pow(2, attempt);
                var jitterMs = Random.Shared.NextDouble() * baseMs;
                return TimeSpan.FromMilliseconds(jitterMs);
            }
        );
}

Honor the Retry-After header when the API sends one, usually with 429 or 503.

What platforms provide built-in retry logic for failed jobs?

Cloud SDKs, job queues and workflow tools all ship with retry logic. Use the built-in retry mechanisms first, then tune them for your workload.

  • AWS SDKs: a standard retry mode with jittered exponential backoff and a set maximum number of attempts.
  • Azure client libraries: retry options for exponential mode, maximum delay and maximum retries.
  • Google Cloud: retry only idempotent operations, exponential backoff, jitter and a deadline.

The same rules apply to third-party APIs. A Google Search API retry strategy, a payments retry plan and embedded integration retry strategies all start with the same checks.

How do you apply retry logic to background jobs?

Background jobs suit retries because nobody waits on the screen. The same rules apply: retry temporary errors, back off and keep the job idempotent.

How to implement backoff and retry for failed transcription API calls?

Upload the audio once, then retry only the status check or the request to start the job. Use exponential backoff with jitter, and give the start request an idempotency key so a retry never starts a second job.

How to implement retry logic for failed API payouts?

Every payout request needs an idempotency key, because a duplicate payout costs real money. Retry only time-outs and 5xx errors, and check the payout’s status before any manual retry.

How to retry failed media processing jobs automatically

Run each job from a queue with a delivery count and backoff. After the last attempt, move the job to a dead-letter queue and alert someone.

How do you apply retry logic to messaging and vendor APIs?

Messages and vendor calls fail in ways you cannot control, so plan for both retries and a fallback. These cases come up often.

How to build reliable retry logic for messaging in a SaaS backend

A software as a service (SaaS) backend should queue every outgoing message with an ID. Workers retry with backoff, and the ID stops a message going out twice.

How do SaaS apps handle retries and failover across different email APIs while keeping templates consistent?

Keep templates in your own app and render them before you call any provider. Each email API then gets the same content. On repeated failures, the worker switches to a second provider and keeps the same message ID.

How do top platforms handle message retries and failover across carriers?

Messaging platforms retry a failed text or call with backoff, then route it through another carrier. Your app should still track each message ID, so a failover never sends the same message twice.

How do you set up automated retries when monitoring shows a vendor’s API is timing out?

Lower the time-out per attempt, add backoff with jitter and cap the total retry time. When time-outs keep coming, open a circuit breaker and retry later.

Does a resend API cancel scheduled retries?

It should, and you should check that it does. Cancel any retries still queued for a request when a person resends it by hand. Otherwise the same request goes out twice.

How should retries work with time-outs, circuit breakers and rate limits?

Set time-outs first, then add retries, a circuit breaker and respect for rate limits. Each guard covers a gap the others leave.

Why set time-outs before retries?

Retries without time-outs can hang threads and use up connections. Set a time-out for each attempt and an overall deadline for all retrying.

When should a circuit breaker stop retries?

A circuit breaker stops calls to a service that is clearly down. During a real outage, retries only add load and delay, so the breaker fails fast and checks again later.

How should you handle rate limits?

Slow down when you get a 429 and wait for the time in Retry-After when the header is there. The 429 status code is defined in Request for Comments (RFC) 6585.

The BoldSign API returns 429 Too Many Requests when you reach the limit. You can also track your usage in its response headers and slow down before you reach it.

What should you log and monitor to keep retries from hiding incidents?

Log every error retry and track it as a metric. A rise in retries often shows up before an outage.

  • Attempt number and total retry count.
  • Final result: success after retrying, or failure.
  • Reason for each retry, such as a time-out, 503, 429 or dropped connection.
  • Delay chosen, and whether Retry-After set it.
  • A trace ID that links every retry to one user request.

What are the most common retry mistakes and fixes?

Most retry bugs come from retrying too much, too soon or in too many places. Each one has a simple fix.

  • Endless retries: always cap attempts and total time.
  • Retrying at once: add exponential backoff with jitter.
  • Retrying a POST with no idempotency key: add the key, or change the flow.
  • Trying to retry all 4xx errors: retry only 429 and other errors that pass.
  • Retries at every layer: share one retry budget across client, gateway and service.

What should you look for in integration tools that handle retries?

Look for retries you can configure, clear error reports and a safe place to test them. Those three things matter more than any feature list.

People often ask what types of tools manage integration connectors, authentication, and retry logic. Integration platforms, workflow engines and API gateways all do. Check these points when you compare who offers integration tools with strong error handling and retry logic:

  • You can set attempts, backoff and which errors to retry.
  • Failed jobs land in a queue you can inspect and replay.
  • Logs show every retry with its reason and result.

What demos let procurement evaluate retry policies, backoff, and connector error handling?

Ask for a sandbox or trial where you can force errors such as 429 and 503. Watch how the tool retries, what it logs and how it reports the final failure.

Which BoldSign plan do you need to call the API in production?

Live API calls need the Enterprise API plan, from $30 a month with 40 envelopes. Each extra envelope costs $0.75, as listed on the BoldSign pricing page in November 2026.

Prices are in USD.

Every other plan gives you sandbox access to the API only. The sandbox is free, and its 50-requests-per-hour limit makes it easy to test how your code handles a 429.

How do you start testing retries against a real API?

The quickest way to learn retries is to watch them run against a real API. Start in a sandbox, where errors cost nothing.

Frequently asked questions

What is retry logic?

Retry logic is code that sends a failed request again after a short wait. Good retry logic retries only temporary errors, waits longer each time and stops after a set number of tries.

Should I retry a 500 error from an API?

Often, yes. Many 500-range errors pass quickly, so retry them a few times with backoff and jitter. Stop retrying when the errors keep coming, because more traffic can make an outage worse.

Should I retry a 429 Too Many Requests error?

Yes, as long as the request is safe to repeat. Wait for the time the Retry-After header gives, or back off on your own when the header is missing.

What is a retry storm?

A retry storm happens when many clients retry at the same moment. The extra traffic hits a service that is already struggling and can turn a short failure into a long outage.

How many retries should I use?

Three to five total attempts suits most API clients. Pair that with a total time limit that matches how long your user can wait.

Where can I find documentation for implementing retry logic?

Start with your cloud provider's retry guide and the docs of the client library you use. The Amazon, Google Cloud and gRPC guides linked in this post each explain backoff, jitter and limits.

Can you walk me through setting up automatic retries for failed API calls in a low-bandwidth clinic app?

Save each request in a local queue first, then send it when the connection allows. Retry with capped backoff and jitter, give each request an idempotency key, and show staff which records are still waiting to sync.

What's the easiest way to set up recurring tasks with retry logic and error handling?

Use a job scheduler or queue that already has retries built in. Set the attempt limit and backoff in its settings, and send jobs that keep failing to a dead-letter queue for review.

Priya Vinayagam

Priya Vinayagam is a Product Manager at BoldSign and an active full-stack developer at Syncfusion, with four years of hands-on experience across .NET and JavaScript. She writes practical, performance-focused technical articles that help developers tackle real-world challenges. Known for looking beyond the obvious, Priya brings a builder’s mindset to every post—breaking down complex problems into clear, actionable solutions. Connect with her on LinkedIn.

More posts by Priya Vinayagam
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required