Claude API Error Handling: Python & TypeScript Production

Originally published at claudeguide.io/claude-api-error-handling-guide

Claude API errors fall into four categories: rate limits (429), authentication (401), invalid requests (400), and server errors (500+). Each category requires a different response: rate limits warrant exponential backoff with jitter, auth errors should page your on-call immediately, bad requests need request inspection, and server errors call for retry with circuit-breaker logic. Getting these four right means your production app survives the edge cases without manual intervention.

---

What error types does the Claude API return?

The Anthropic SDK maps every HTTP status code to a typed exception. Here is the full reference:

Error	HTTP Status	SDK Exception	When it happens
Rate limit	429	RateLimitError	Too many requests or tokens per minute
Auth error	401	AuthenticationError	Invalid or missing API key
Permission	403	PermissionDeniedError	Key lacks required capability
Not found	404	NotFoundError	Invalid model name or endpoint
Invalid request	400	BadRequestError	Malformed message structure
Server error	500/529	InternalServerError	Anthropic-side issue
Overloaded	529	APIStatusError	Service temporarily overloaded

The SDK raises these as Python exceptions (or TypeScript Error subclasses) — you do not need to inspect raw HTTP status codes in your application logic. Catch by exception type and your logic stays clean.

---

How do you implement exponential backoff for Claude API rate limits in Python?

The pattern below covers RateLimitError and InternalServerError, adds random jitter to avoid thundering-herd problems, and gives up after a configurable number of attempts:

python
import anthropic
import time
import random
from typing import Callable, TypeVar

T = TypeVar("T")
client = anthropic.Anthropic()

def with_retry(
    fn: Callable[[], T],
    max_retries: int = 3,
    base_delay: float = 1.0,
) -

[-

*30-day money-back guarantee. Instant download.*

---

## Related guides

- [Claude API Rate Limits: Production Guide and Handling Strategies](/claude-api-rate-limits-production)
- [Claude API Python Tutorial: Complete Guide with Code Examples](/claude-api-python-tutorial)
- [Claude Agent Production Deployment: Fly.io, Vercel, and Lambda](/claude-agent-production-deploy)