Handling Claude API errors without guessing

Why "just retry on failure" isn't a strategy

A request to any API can fail for reasons that span a wide range of severity, and treating every failure the same way — retry a few times, then give up — either wastes time retrying something that was never going to succeed no matter how many attempts you give it, or gives up too early on something that was a genuinely transient blip. The right handling depends entirely on which category a given error actually falls into, and that category is usually recoverable from the error itself if your code actually inspects it rather than treating every non-200 response identically.

Errors that mean your request was wrong

A request rejected because it was malformed, referenced an unsupported combination of parameters, or used a field a specific model doesn't accept is not going to succeed on retry — the request itself needs to change, and retrying it as-is just repeats the same failure while burning time and, depending on your retry logic, potentially rate-limit budget too. This category is genuinely common on this site's own error catalogue: a sampling parameter a newer model rejects, an effort level a given model doesn't support, a tool declared without its matching connector. Treat any error that describes a specific problem with the request body as a signal to fix the request, not a signal to retry it.

Errors that mean try again, later

A different category of failure is transient by nature — the service is temporarily overloaded, a rate limit was hit, a network blip interrupted the connection. These genuinely do resolve on retry, but naively retrying immediately in a tight loop tends to make the underlying problem worse rather than better, especially at any real request volume. Backing off with increasing delay between attempts, and capping the total number of attempts rather than retrying indefinitely, is the standard shape here — and it matters more as your request volume grows, since a burst of simultaneous immediate retries from many callers is itself a common cause of sustained overload.

Errors that mean something structural changed

A model id that no longer resolves, or a parameter that used to work and now doesn't, usually means something changed on the platform side rather than in your request specifically — a retirement, a capability that shifted between model generations. No amount of retrying fixes this category, and treating it like a transient failure just delays noticing that an actual code change is needed. See the model ID you're calling has been retired and what actually changed from Opus 4.6 to Opus 5 for the kind of structural change that produces this category of error.

Reading the error body, not just the status code

The status code alone tells you the broad category of failure; the error body usually tells you specifically what was wrong, and skipping past it in favour of a generic "something failed, retry" handler throws away the information that would let you fix the actual problem instead of just absorbing the failure. Log the full error body during development at minimum, even if your production handling only surfaces a simplified message — you'll need the detail the first time a new failure mode shows up that your existing handling wasn't built for.

Building a handler that ages well

An error handler written against today's error catalogue will miss whatever's added next — new models bring new failure modes, and a handler that only special-cases errors you've already seen will silently mishandle ones you haven't. Default to a conservative fallback for anything unrecognised — surface it rather than silently swallowing it or blindly retrying — so a new error type gets noticed and handled deliberately rather than absorbed into whichever bucket happened to be the default case.