Skip to content

Retry Mechanism

Flaky networks shouldn’t fail your suite.

Retry failed curl requests with a count, delay and backoff. 429, 500, 502, 503 and 504 retry by default; a 400 doesn’t.

Read the docsInstall curl-runner
retry.yaml
global:
  defaults:
    retry: { count: 3, delay: 1000, backoff: 2, retryableStatuses: [429, 500, 502, 503] }

requests:
  - name: Flaky upstream
    url: https://api.example.com/data
    retry:
      count: 5
      delay: 2000

Benefits

  • Exponential backoff

    Each attempt waits longer than the last, so a struggling server gets room to recover.

  • Per request or global

    Set a default for the file, override it on the one endpoint that needs more patience.

  • Only the right failures

    Retries 429, 500, 502, 503 and 504, never a 400 your request deserved. Dropped connections and timeouts retry too, and a 429’s Retry-After is honoured.

From curl --retry

curl’s --retry N retries transient errors only, waiting 1 second and doubling the wait on each attempt. --retry-delay S replaces that with a fixed wait of S seconds. The YAML equivalent:

curl
curl --retry 3 --retry-delay 2 https://api.example.com/data
retry-from-curl.yaml
request:
  name: Flaky upstream
  url: https://api.example.com/data
  retry:
    count: 3
    delay: 2000
    retryableStatuses: [408, 429, 500, 502, 503, 504]

curl-runner convert maps these flags for you: --retry N becomes count N with a 1000 ms delay, a backoff of 2 and the transient status codes 408, 429, 500, 502, 503 and 504; --retry-delay S turns it into a fixed delay of S × 1000 ms. On top of that, a retry policy can be set per request or as a default for the file, and retryableStatuses lets you choose which statuses are worth another try. curl’s documentation for --retry.

Good for

  1. Intermittent network failures in CI
  2. Rate-limited APIs that answer 429
  3. Services that take a moment to warm up after a deploy
  4. Smoke tests against shared staging environments