Back off and retry a 429

Every busy integration eventually hits a rate limit. Handling it well is the difference between a brief pause and a cascade of failed requests. This recipe reads the live rate-limit headers Phosra puts on every /api/v1/* response, drives the sandbox into a real 429, and wraps your calls in a retry that waits exactly as long as the server tells it to — no guessing, no thundering herd.

flowchart LR
  A["GET /api/v1/platforms<br/>read X-RateLimit-*"] --> B{"remaining > 0?"}
  B -->|yes| C["send request"]
  B -->|no| D["sleep until<br/>X-RateLimit-Reset"]
  C --> E{"status 429?"}
  E -->|no| F["done"]
  E -->|yes| D
  D --> C

Every request and response below is verbatim live output, captured against https://phosra-api-sandbox-production.up.railway.app. No API key, nothing to install — the sandbox rate-limits anonymous callers on the same headers production uses.

Before you start

export PHOSRA_BASE="https://phosra-api-sandbox-production.up.railway.app"

1. 1
   Read your rate-limit budget off any response

   Every /api/v1/* response carries three headers. Read them on the response you already made — you do not need a separate "check my quota" call.

   CodeCodeCode

   bash
   curl -s -D - -o /dev/null "$PHOSRA_BASE/api/v1/platforms" | grep -i x-ratelimit

   Live headers on a normal 200:

   http

   x-ratelimit-limit: 100
   x-ratelimit-remaining: 92
   x-ratelimit-reset: 1783336980

   Header	Meaning
   X-RateLimit-Limit	Requests allowed per window (100 on the sandbox).
   X-RateLimit-Remaining	Requests left in the current window. Watch this — when it hits 0, the next request is a 429.
   X-RateLimit-Reset	Unix epoch seconds when the window resets and Remaining returns to Limit.

2. 2
   Drive a real 429

   Exhaust the window and the very next request is rejected. Loop past the limit and you will see the counter fall to 0, then a 429. This is the exact loop that produced the response below — request 101 was the first to be limited:

   CodeCodeCode

   bash
   for i in $(seq 1 130); do
     code=$(curl -s -o /dev/null -w "%{http_code}" "$PHOSRA_BASE/api/v1/platforms")
     if [ "$code" = "429" ]; then
       echo "429 at request $i"
       curl -s -D - -o /dev/null "$PHOSRA_BASE/api/v1/platforms" \
         | grep -iE 'http/|retry-after|x-ratelimit'
       break
     fi
   done

   The live 429 — status line, both timing headers, and the body:

   http

   HTTP/2 429
   retry-after: 60
   x-ratelimit-limit: 100
   x-ratelimit-remaining: 0
   x-ratelimit-reset: 1783337040
    
   Too Many Requests

   The 429 body is the plain-text string Too Many Requests, not JSON. Do not JSON.parse a 429 — branch on the status code and read the headers. (Every other error class — 400, 401, 403, 404, 409, 422 — returns a JSON body; 429 and 5xx are the exceptions.)

   Phosra sends both timing headers on a 429:

   Header	Value	Use
   Retry-After	60	Seconds to wait — the simplest signal, present only on the 429.
   X-RateLimit-Reset	1783337040	Absolute Unix time the window resets — present on every response, so you can wait before you ever hit the limit.

   Prefer X-RateLimit-Reset (it lets you pace proactively); fall back to Retry-After when it is absent.

3. 3
   Wrap every call in a reset-aware retry

   Put it together: on a 429, sleep until the reset the server named, then retry once. This is the whole contract — a 429 is never a failure you surface to the user, it is a "wait and try again."

   CodeCodeCode

   bash
   # fetch_with_retry URL — retries a single 429 after waiting for the reset.
   fetch_with_retry() {
     local url="$1"
     local body headers code reset now
     headers=$(curl -s -D - -o /tmp/body "$url" -w "%{http_code}")
     code=$(printf '%s' "$headers" | tail -c 3)
     if [ "$code" = "429" ]; then
       reset=$(printf '%s' "$headers" | grep -i '^x-ratelimit-reset:' | tr -d '\r' | awk '{print $2}')
       now=$(date +%s)
       sleep $(( reset > now ? reset - now : 1 ))
       curl -s "$url" -o /tmp/body            # retry once
     fi
     cat /tmp/body
   }
    
   fetch_with_retry "$PHOSRA_BASE/api/v1/platforms"

   Retry once, not forever. After one wait-and-retry the window has reset, so a second 429 means you are sending faster than the limit sustains — throttle your own concurrency instead of looping. The right ceiling is a bounded retry (1–2 attempts), never an unbounded while.

When to retry — the full table

A 429 is retryable; most errors are not. Retrying a deterministic 4xx just returns the same error and burns your budget.

The whole flow at a glance

Next steps