Anthropic 500 api_error and 504 timeout_error: retry with backoff, stream the long ones

TL;DR: A 500 is an internal Anthropic failure. A 504 is a request that timed out in processing. Retry with exponential backoff. Use exponential backoff with jitter on both.

500 and 504: retry the first, stream the second

500 api_error

An unexpected error inside Anthropic's systems. Retry with exponential backoff. If it persists across retries and time, contact support and include the requestid from the error body. One ticket with a requestid beats ten retries.

504 timeout_error

The request timed out while processing. For long-running requests, switch to the streaming Messages API so partial progress arrives instead of one all-or-nothing response. Anthropic's long-request guidance covers the other options.

What to do

1. Classify: 500 means retry the same request; 504 means retry once, and if it 504s again, restructure to streaming.
2. Use exponential backoff with jitter on both. Honor retry-after if present.
3. Always capture the request_id from the error body. For persistent 500s it is the single most useful thing you can hand support.
4. The request-id response header carries the same identifier, and SDKs expose it on response objects, so you can correlate even when the body is lost.

The trap

Retrying a 504 the same way five times and being surprised at the sixth timeout. A request that cannot finish in the window will not finish on retry three either. Streaming is the fix, not patience. The other trap: reporting a 500 to support without the request_id, which turns a quick lookup into a guessing game.

Checklist

• 504 twice in a row: stop retrying non-streaming and switch to the streaming API.
• Keep the request_id for every failed request in your logs. It costs nothing and saves hours.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Anthropic 500 apierror and 504 timeouterror.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Anthropic behavior.

Anthropic's error reference: 500 apierror is internal, retry with exponential backoff and contact support with the request ID if persistent; 504 timeouterror means the request timed out, consider streaming for long requests. Verified live at https://platform.claude.com/docs/en/api/errors.