Which error it is and what to do, retry, fix or reroute

A worker retries every failure five times, without checking which one it is. The audit finds thousands of retries that could never succeed and a dashboard reading “100% success” while truncated answers get saved. Before choosing a recovery strategy, you need to know what kind of error you are facing.

The question to ask

If I send exactly the same request a little later, can it succeed? If the answer is yes, it is a transient error and you retry. If it’s no, retrying only wastes time and quota: you have to fix the request or send it down another path.

HTTP errors

Code and type	What it means	What to do
429 rate_limit_error	You exceeded a rate limit	Retry with exponential backoff and jitter, honoring retry-after
500 api_error	Internal error at Anthropic	Retry with backoff
529 overloaded_error	The API is overloaded	Retry with backoff
504 timeout_error	The request took too long	Move to streaming or batches for long requests
400 invalid_request_error	The request is malformed or uses something the model doesn’t accept	Read the message and fix it; never retry it unchanged
401 / 403	Invalid key or no permission	Check credentials and permissions
413 request_too_large	The request is too large	Shrink the input or use another route (for example, files)

The official SDK already retries connection errors, 429s and 5xx errors with backoff (twice by default). If you also wrap every call in your own five-retry loop, you multiply the load exactly when the API is saturated.

A 400 that appears after changing the model ID is usually a breaking change between versions, such as the assistant message prefill that newer models no longer accept. The error message says so.

What arrives with HTTP 200

Here is the trap: several problems are not HTTP errors. You have to check the stop_reason of every response.

• max_tokens: the response hit the configured limit and was cut off. If output_tokens matches the limit, raise max_tokens for that feature and don’t show the text as complete. Switching to a larger model doesn’t fix it.
• refusal: the model declined. It arrives as a 200, so a dashboard that counts HTTP codes never sees it. These cases go down another path: rephrasing, a fallback model or human review.
• With streaming, an error can arrive as an error event inside the stream, after the API has already answered 200. If there is no message_stop, the response is incomplete: discard it and retry with backoff.

The usual traps

• Retrying a 400, 401 or 403 “just in case”.
• Retrying without backoff, or all clients at once, without jitter.
• Ignoring retry-after.
• Saving everything that came back with a 200 as a success without checking stop_reason.
• Changing the model or the prompt before reading which error it is.

On the exam

Read the code, the error type and the stop_reason the scenario gives you: the clue is almost always there. If the question asks which ones to retry, choose the transient ones (429, 500, 529) and rule out those that describe a problem with the request or the credentials. If everything returns 200 but the results are wrong, look for the option that branches on stop_reason.