How Do You Stop Claude Swallowing API Errors?
Tell it, in the prompt and in CLAUDE.md, that no catch block may log and continue, that every request has a timeout, and that failures must surface as typed errors carrying the request ID. Then have a review check for it, because Anthropic says a CLAUDE.md line is followed nearly every time, not every time.
Go through [path to the client or integration]. Find every place an external call can fail without anyone finding out: - catch blocks that log and continue, or return null or an empty list - requests with no timeout - responses used without checking the status - JSON parsed without handling a non-JSON body - streams where an error can arrive after a 200 List them first, with file and line. Then fix each one so that: - failures raise a typed error naming the operation, status and request ID - retries happen only for [timeouts, 429 with retry-after, 5xx], with capped backoff, and not on top of what the SDK already retries - anything that should degrade instead is explicit, and I've approved it Add a test per fix that makes the call fail and asserts the error. Run them and show the output.
- Raise a typed error
- Set a timeout on every request
- Log the request ID
- Requeue on a rate limit
- Log and continue
- Return null on failure
- Check only the status on a stream
- Retry a write with no idempotency key
- 404anthropic.NotFoundError
- 429RateLimitError
- TimeoutAPITimeoutError
- Connection problemAPIConnectionError
Try it now
- 1Paste the prompt in Claude Code for one integration, and read the list before you let it fix anything.
- 2Add this to
CLAUDE.md:External calls set a timeout and raise typed errors. Never catch and continue. - 3Run
/code-reviewon the result. It follows that rule along with the rest of yourCLAUDE.md. - 4Break your API key on purpose and run the job. It worked if it exits with a named error instead of finishing quietly.
Use it when
Anything that crosses a network boundary, and anything that runs unattended, such as cron jobs, webhooks, queues and batch runs, where nobody is watching a console.
Skip it when
Places where carrying on is the right design, such as an optional recommendations panel that can show nothing. The fallback must then be deliberate, and logged so you can see how often it happens. A short script you're watching can simply crash, which is already loud.
Why it works
Code that swallows an error doesn't fail where the problem is. It fails three layers later with an unrelated message, or never visibly fails at all. Typed errors keep the cause at the boundary. Anthropic's Python SDK shows a shape to copy: a 404 raises anthropic.NotFoundError, a 429 raises RateLimitError, a timeout raises APITimeoutError, and a connection problem raises APIConnectionError. Every response also has a request-id header, exposed as message._request_id, which gives you something to trace. The review step holds up because /code-review follows your CLAUDE.md, so the rule you wrote for writing code is also applied when reviewing it.
Example
Say a webhook processor catches everything and returns 200 to the sender, so events vanish whenever a downstream API returns a 429. Asking for loud failures should give you a RateLimited error and a requeue instead. Streams need the same care. Anthropic's docs show this arriving mid-stream, after the 200 has already been sent: data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}. A handler that checks only the status never sees it.
Going further
A stream that dies midway leaves partial data, and the recovery differs by model. Anthropic's streaming docs say to save what arrived, then send a new request. For Claude 4.6 and later, that request carries the partial text in a user message with an instruction to continue, since these models reject a prefilled assistant message with a 400. For debugging, setting ANTHROPIC_LOG=debug turns on the Python SDK's logging. Its ValueError on a long non-streaming request is also a useful signal: it fires when a request is expected to take over about 10 minutes, so move that call to streaming.
Common mistakes
- Accepting a
try/catchthat logs and returnsnull. The caller then treats an outage as an empty result. - Wrapping a retry loop around an SDK that already retries twice by default. Remove your loop, or set
max_retries. - Logging the message but not the request ID, so you can't trace the failure or quote it to support.
- Retrying a write with no idempotency key, which can turn one timeout into two charges.
Sources
- Python SDK, Claude Platform Docs
- Claude API errors, Claude Platform Docs
- Streaming messages, Claude Platform Docs
- Review locally with /code-review, Claude Code docs
- Best practices, Claude Code docs
Checked 6 November 2026. Products change often, so confirm details with the vendor.