X API Errors: Which Ones to Retry and Which to Stop On

11 min readSocialAPI Engineering

X API Errors: Which Ones to Retry and Which to Stop On

Most error handling for APIs is written twice. The first version catches everything and retries it. The second version is written after that retried a 402 eleven thousand times overnight.

The useful distinction isn't error versus success. It's will the identical request succeed later? Three codes say yes, several say never, and one says "not without a change at your end." Getting those groups right is most of what error handling is.

There's a free demo endpoint if you want to trigger real responses while writing handlers, rather than guessing at shapes.


The error envelope

Failures come back in a consistent shape — this is a real response, captured while writing this:

{
  "status": "error",
  "error": { "code": 401, "message": "invalid or revoked API key" },
  "request_id": "req_1794064042133_12236",
  "credits_used": null
}

credits_used: null on a failure is the part worth noticing. A failed request didn't bill you, which changes the economics of retrying: a retry after a 429 costs nothing but time.

Log the request_id. It's the only thing that lets anyone correlate your failure with a server-side record. A support conversation that starts with a request ID gets an answer; one that starts with "it was failing yesterday" generally doesn't.


The decision table

Code Meaning Retry? What to do
429 Rate limited Yes Back off and retry. Not billed.
502 / 503 Upstream or service unavailable Yes Exponential backoff, cap the attempts
500 Server error Once or twice If it persists, it's not transient
402 Out of credits Never Alert someone. Identical request fails identically.
401 Bad or revoked key Never Fix the key. Retrying cannot help.
403 Forbidden Never You're asking for something not permitted
404 Not found Never The account or post doesn't exist, or is protected
400 / 422 Bad request Never Your parameters are wrong — fix the call

The line that matters runs between 429/5xx and everything else. Above it, waiting changes the outcome. Below it, the request is deterministic — retrying is a loop that burns time and, if you're paying per request elsewhere, money.

RETRYABLE = {429, 500, 502, 503, 504}

def should_retry(status: int, attempt: int, max_attempts: int = 3) -> bool:
    if status not in RETRYABLE:
        return False            # deterministic failure — stop
    return attempt < max_attempts

That's the whole policy. Everything else is backoff arithmetic.


404 is the one people get wrong

A 404 on a user lookup has at least four distinct causes, and they need different responses:

Cause How to tell What to do
Handle doesn't exist Permanent Mark it invalid, stop asking
Account renamed Another handle now has that ID Re-resolve by user ID, not handle
Account suspended Was working, now 404s Record the date, keep the data
Account protected Exists publicly, not readable Mark it, don't retry

Handles are mutable; user IDs are not. If you're tracking accounts over time, store the numeric ID as your key and treat the handle as a display attribute — the same reasoning that makes IDs the right primary key in storage. Accounts that rename will otherwise silently disappear from your collection and look like deletions.

Never retry a 404 on a schedule. The one defensible pattern is a slow re-check — weekly, not minutely — because suspensions are occasionally reversed. Minute-level retries on a nonexistent account are how people accidentally spend their whole quota on nothing.


429 is three different things

This is the failure most worth understanding, because the correct wait differs by cause:

  • Per-second burst — you fired a hundred requests concurrently. Fixed by bounding concurrency, not by waiting longer.
  • Per-window quota — you've used your allowance for the current window. Fixed by waiting for the window to roll.
  • Upstream pressure — the provider is throttling at its own source. Fixed only by waiting; your concurrency isn't the problem.

They return the same status code, so you can't distinguish them from one response. What you can do is respond in a way that's correct for all three: back off exponentially, cap the delay, and bound your concurrency independently. The full breakdown is in what rate limit exceeded means.

import random, time

def backoff_delay(attempt: int, base: float = 1.0, cap: float = 60.0) -> float:
    """Exponential with full jitter, capped."""
    raw = min(cap, base * (2 ** attempt))
    return random.uniform(0, raw)

The jitter is not decoration. Without it, every worker that hit the same rate limit retries at the same instant, so your fleet self-synchronises into a thundering herd and trips the limit again. Randomising the delay spreads the retries out, and it's one line.


Auth is checked before routing

A small but confusing behaviour, verified against the live API: requesting a route that doesn't exist without a valid key returns 401, not 404.

$ curl -s "https://api.socialapi.tech/v1/does/not/exist"
{"status":"error","error":{"code":401,"message":"invalid or revoked API key"},...}

This is normal for APIs that authenticate at the edge, and it matters for debugging: if you're getting 401 on a call you believe is authenticated, check the URL before you regenerate your key. A typo in the path and a bad key produce the same response, and people usually suspect the key first.


Timeouts aren't errors, they're unknowns

A timeout is the one case where you genuinely don't know what happened. The request may have been processed, or not.

For reads that doesn't matter — retry freely, since fetching twice is harmless. It matters when the request had an effect, which for a read-only API mostly means your own bookkeeping:

def fetch_with_state(api, target, state):
    try:
        rows = api.fetch(target)
    except TimeoutError:
        # DON'T advance the cursor — we don't know if we got that page
        state.mark(target, "unknown")
        return None
    state.advance(target, rows)
    return rows

The rule: on an ambiguous failure, don't advance state. Re-reading a page costs one request. Skipping one silently loses data you'll never know is missing — the same reasoning as not advancing a high-water mark after a rate limit.


A handler worth copying

import requests, time, random

RETRYABLE = {429, 500, 502, 503, 504}

class Permanent(Exception): pass
class OutOfCredits(Permanent): pass

def call(url, params, headers, max_attempts=4, timeout=30):
    last = None
    for attempt in range(max_attempts):
        try:
            r = requests.get(url, params=params, headers=headers, timeout=timeout)
        except requests.Timeout:
            last = "timeout"                       # unknown: retry, don't advance state
            time.sleep(random.uniform(0, min(60, 2 ** attempt)))
            continue
        except requests.RequestException as e:
            raise Permanent(f"network: {e}")       # DNS, TLS — not worth retrying blind

        if r.status_code == 200:
            return r.json()

        body = {}
        try:
            body = r.json()
        except ValueError:
            pass
        err = (body.get("error") or {})
        rid = body.get("request_id", "?")

        if r.status_code == 402:
            raise OutOfCredits(f"{err.get('message')} [{rid}]")
        if r.status_code not in RETRYABLE:
            raise Permanent(f"{r.status_code} {err.get('message')} [{rid}]")

        # retryable: honour Retry-After when present
        wait = r.headers.get("Retry-After")
        delay = float(wait) if wait and wait.isdigit() \
                else random.uniform(0, min(60, 2 ** attempt))
        last = f"{r.status_code} [{rid}]"
        time.sleep(delay)

    raise Permanent(f"gave up after {max_attempts}: {last}")

Three choices in there are deliberate.

OutOfCredits is its own exception type. It needs a different response from every other failure — a human has to act — so it shouldn't be caught by the same handler that logs and moves on.

Retry-After is honoured when present. If the server tells you how long to wait, guessing is worse than listening.

Network exceptions raise rather than retry. A DNS or TLS failure is usually configuration, and retrying it four times just delays discovering that.


Our API returns the envelope above on every failure, with a request_id on both successes and errors. Signing up with Google includes $0.20 in free credits and no card, which is enough to trigger each of these codes deliberately and confirm your handler does the right thing with each.


FAQ

What does a 429 mean on the X API? You're rate limited. The request wasn't billed, and the same request will succeed later — back off and retry rather than treating it as a failure.

Is a rate-limited request charged? No. A failed response comes back with credits_used: null, which is why retrying a 429 costs time but not money.

Should I ever retry a 402? No. It means you're out of credits and will keep meaning that until someone tops up. Give it its own exception type so a human gets alerted.

What causes a 401 from the API? A missing, malformed or revoked key — or a URL that doesn't exist, because auth is checked before routing. Check the path before regenerating the key.

Why do I get 401 instead of 404 for a bad URL? Because authentication happens at the edge, before route matching. A typo in the path and an invalid key produce the same response, which is a common debugging trap.

What's the difference between 401 and 403? 401 means we don't know who you are; 403 means we do and you're not permitted. Neither is fixed by retrying.

What does a 404 mean for a user lookup? One of four things: the handle never existed, the account was renamed, it was suspended, or it's protected. They need different handling, so don't collapse them.

How do I handle an account that was renamed? Key your records on the numeric user ID, not the handle. IDs are immutable; handles are not, so handle-keyed records silently vanish on rename.

Should I retry a 404? Not on a schedule. A slow re-check — weekly — is defensible since suspensions are sometimes reversed. Minute-level retries on a nonexistent account waste quota.

How can I tell a suspension from a deletion? You often can't from the response alone. Record when the 404 first appeared and keep the data you already collected; the transition date is usually the informative part.

Which status codes are worth retrying? 429, 500, 502, 503 and 504. Everything else is deterministic — the identical request will fail identically.

How many retries is reasonable? Three or four attempts with exponential backoff. If it hasn't succeeded by then, it's probably not transient, and more attempts delay the alert.

What backoff should I use? Exponential with full jitter and a cap — something like random.uniform(0, min(60, 2**attempt)).

Why does jitter matter? Because without it, every worker that hit the same limit retries simultaneously. Your own fleet synchronises into a thundering herd and trips the limit again.

Should I honour the Retry-After header? Yes, when it's present. The server knows better than your backoff formula; fall back to the formula only when the header is absent.

How should I handle timeouts? As unknowns, not errors. Retry the read, but don't advance any cursor or high-water mark — you don't know whether that page was delivered.

Why shouldn't I advance state after a timeout? Because re-reading a page costs one request, while skipping one silently loses data you'll never discover is missing.

Should I retry on a connection error? Usually not blind. DNS and TLS failures are typically configuration, and four retries just postpone finding that out.

What should I log on a failure? Status code, the error message, and the request_id. The request ID is the only field that lets anyone trace your failure server-side.

What is request_id for? Correlating your client-side failure with the server's record of it. Support questions that include one get specific answers.

What does a 400 usually mean? A malformed parameter — a bad limit, a wrong cursor, a missing required field. Don't retry it; fix the call.

How do I distinguish the three kinds of 429? You can't from a single response. Respond correctly for all three instead: exponential backoff with jitter, plus bounded concurrency so you aren't causing the burst variant yourself.

Should rate limit handling live in my client or my job? The client, so every call gets it. Job-level handling means every new call site reinvents it, and one of them gets it wrong.

What's the difference between 500 and 502? 500 is an error inside the service; 502 means an upstream dependency failed. Both are worth retrying, but a persistent 500 is more likely to need reporting.

Do errors count against my rate limit? Rate-limited responses don't bill, but they do indicate you've reached a boundary. The fix is pacing, not retry volume.

What's the one error-handling mistake to avoid? Treating all failures as retryable. One 402 in a retry loop can consume an entire night of runtime while changing nothing.


The split between 429/5xx and everything else is the only distinction you really have to get right; the rest is backoff arithmetic. A Google sign-up includes $0.20 in free credits and no card if you want to trigger each code against a live endpoint.