TypeScript SDK Error Class Reference

Because in the TypeScript SDK APIConnectionError is a subclass of APIError, not a sibling. An instanceof Anthropic.APIError check matches connection errors too, so if that check comes first in an if/else if chain, the more specific APIConnectionError branch never executes.

No. In the Python SDK, APIConnectionError is a sibling of APIError, not a subclass. Code ported from Python to TypeScript that assumes the same relationship will silently skip the connection-error branch.

Not usually. The SDK already auto-retries 429, 5xx, and connection errors with exponential backoff, using a default maxRetries of 2. Only add your own retry logic if you need a different retry count, backoff strategy, or queuing behavior.

BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), and UnprocessableEntityError (422). Retrying these wastes a request since the payload or credentials, not the network or server load, caused the failure.

Any typed SDK error that didn't match a more specific instanceof check earlier in the chain, since every specific error class extends APIError. Put it last in a catch chain as a safety net, not as your primary handling path.

.status is the HTTP status code (a number, like 429). .type is the API's own error type string (like "rate_limit_error" or "overloaded_error"), which lets you distinguish causes that share the same status code.

Yes, overloaded_error can arrive under a 429 or a 5xx status depending on the cause, which is exactly the case where checking .type in addition to the status-mapped class gives you more precise information.

Anything that prevents a response from arriving at all, such as a DNS failure, a dropped connection, or a client-side timeout. It's distinct from the status-code errors because no HTTP response was ever received.

For a small app, a shared wrapper function (like askClaude above) that centralizes the catch chain keeps handling consistent. For larger apps, wrap the catch chain in a utility so every call site gets the same retryable/non-retryable classification without duplicating the if/else if chain.

Yes. The final else in the example re-throws anything that isn't an SDK APIError at all, such as a bug in your own calling code. Swallowing non-SDK errors silently makes real bugs harder to find.

Less common than BadRequestError, since it means the request was syntactically valid JSON but failed a semantic check, such as a value that's the right type but out of an allowed range.

The example uses claude-sonnet-5, the default model in the current Claude lineup (Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5, Claude Haiku 4.5). Swap in whichever model your application targets.