Retries

Retrying a write on this API is always safe, provided you resend the same Idempotency-Key. That is the whole reason the header is mandatory.

What to retry

Response	Retry?	How
`429 rate_limited`	Yes	Sleep for `Retry-After`, then once
`500`, `502`, `503`, `504`	Yes	Exponential backoff with jitter
Timeout or connection reset	Yes	Same as above, same idempotency key
`409 idempotency_key_in_progress`	Yes	Short pause, same key
`400`, `401`, `403`, `404`, `413`, `422`	No	Fix the request

Never retry a 4xx other than 429 and idempotency_key_in_progress. The request will fail identically forever, so a retry loop is load with no chance of success.

Because client faults are never returned as 5xx on this API, the split above is reliable: a 5xx really does mean our side, and retrying it is reasonable.

The timeout case

This is the case retries exist for, and the one people get wrong. When a request times out you do not know whether the server acted. The connection died, but the write may well have committed. Without an idempotency key your options are to retry and risk a duplicate order, or not retry and risk losing it. With one, retry. If the original committed, you get its stored response back and nothing happens twice. If it never arrived, it runs now.

KEY=$(uuidgen)

# times out with no response
curl -X POST https://api.mercemur.com/api/v1/orders \
  -H "Idempotency-Key: $KEY" ...

# safe: same key, replays or executes, never duplicates
curl -X POST https://api.mercemur.com/api/v1/orders \
  -H "Idempotency-Key: $KEY" ...

Generate the key before the first attempt and hold it for every retry of that operation. A key generated inside the retry loop is a new key each time, which reinstates exactly the duplicate-write risk you were trying to avoid.

Backing off

Honour Retry-After when it is present

On a 429 the server tells you exactly how long to wait. Use that number rather than your own schedule.

Otherwise back off exponentially

Roughly 1s, 2s, 4s, 8s, 16s. A fixed short delay against an overloaded service adds load at the worst moment.

Add jitter

Randomise each delay by up to a few hundred milliseconds. Without it, every client that failed at the same instant retries at the same instant, and the recovering service is hit by a synchronised wave.

Cap the attempts

Five is usually right. Beyond that you are not recovering from a blip, and the failure should surface to a human or a dead letter queue.

A worked implementation

async function withRetry(fn, max = 5) {
  const key = crypto.randomUUID()   // once, outside the loop

  for (let attempt = 0; attempt < max; attempt++) {
    let res
    try {
      res = await fn(key)
    } catch (err) {
      if (attempt === max - 1) throw err
      await sleep(2 ** attempt * 1000 + Math.random() * 300)
      continue
    }

    if (res.ok) return res

    if (res.status === 429) {
      await sleep(Number(res.headers.get("retry-after")) * 1000)
      continue
    }
    if (res.status >= 500) {
      await sleep(2 ** attempt * 1000 + Math.random() * 300)
      continue
    }

    return res   // a 4xx: do not retry
  }

  throw new Error("exhausted retries")
}

import random, time, uuid

def with_retry(fn, max_attempts=5):
    key = str(uuid.uuid4())          # once, outside the loop

    for attempt in range(max_attempts):
        try:
            res = fn(key)
        except (requests.Timeout, requests.ConnectionError):
            if attempt == max_attempts - 1:
                raise
            time.sleep(2 ** attempt + random.random() * 0.3)
            continue

        if res.ok:
            return res

        if res.status_code == 429:
            time.sleep(int(res.headers["retry-after"]))
            continue
        if res.status_code >= 500:
            time.sleep(2 ** attempt + random.random() * 0.3)
            continue

        return res                   # a 4xx: do not retry

    raise RuntimeError("exhausted retries")

Reads

GET requests are naturally safe to retry and take no idempotency key. Apply the same backoff rules. If a paged walk fails mid-way, retry the failed page with the same after cursor. You do not need to restart the walk.

When to stop and alert

Retries hide transient failures, which is their job. They should not hide a persistent one. If an operation exhausts its attempts, surface it: a log at error level with the x-request-id, a dead letter queue, or an alert. Silently dropping a failed write after five attempts is how an integration ends up quietly missing orders.

Get started

Essentials

Authentication

Make requests

Error handling

What to retry

The timeout case

Backing off

A worked implementation

Reads

When to stop and alert

​What to retry

​The timeout case

​Backing off

​A worked implementation

​Reads

​When to stop and alert

What to retry

The timeout case

Backing off

A worked implementation

Reads

When to stop and alert