ClaudeAPI integrationLevel 2: Context

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.

Prompt to copy
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.
Do
  • Raise a typed error
  • Set a timeout on every request
  • Log the request ID
  • Requeue on a rate limit
Don't
  • Log and continue
  • Return null on failure
  • Check only the status on a stream
  • Retry a write with no idempotency key
Rule of thumb, not an Anthropic chart, drawn from the failure patterns on this page.
  • 404anthropic.NotFoundError
  • 429RateLimitError
  • TimeoutAPITimeoutError
  • Connection problemAPIConnectionError
How Anthropic's Python SDK turns failures into typed errors, per its docs. A shape to copy in your own client.

Try it now

  1. 1Paste the prompt in Claude Code for one integration, and read the list before you let it fix anything.
  2. 2Add this to CLAUDE.md: External calls set a timeout and raise typed errors. Never catch and continue.
  3. 3Run /code-review on the result. It follows that rule along with the rest of your CLAUDE.md.
  4. 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/catch that logs and returns null. 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

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course