Claude and the Anthropic SDK · Chapter 18 of 21
Errors, retries and rate limits
By the end of this chapter you can tell every error Claude's API can give you apart by its class in the SDK, say which ones are worth trying again and which never are, see what the SDK already retries for you and tune it, write your own retries with backoff and jitter, read the rate-limit headers on every reply, keep under a tight limit with the cache, and handle a stream that breaks halfway through an answer. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Cost
- 4 tasks
- Python
- In the all labs plan
The first 2 chapters of Claude and the Anthropic SDK are free. This one comes with the all labs plan.
Why you need this
Sahay goes live on Monday. Until now every request in this lab succeeded, because nothing else was asking. In production, Claude's API is shared with everyone else's traffic. Some minutes it is busy and answers 529 overloaded_error. Parchi's key has a limit on requests and tokens a minute, and a burst of families on a Monday morning goes past it: 429 rate_limit_error. A network hiccup loses a reply altogether. And a teammate's typo in a model id fails every single time, no matter how often you try.
Meher has one rule: "A family should never see a traceback." Kamla adds a second: "And never half an answer." Arjun knows the two mistakes teams make here. One is to retry nothing, so a busy minute becomes a failed claim. The other is to retry everything, so a request that can never succeed is sent again and again, and a busy API is made busier. The answer is in between: know which errors can pass, wait the right time, and give up cleanly.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
what_went_wrong.py: what went wrong?
Write explain(e) -> Verdict (Verdict is given: kind, retry, request_id). kind is the name of the first class the error is an instance of, in this order: BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError, OverloadedError, InternalServerError, APIConnectionError, APIStatusError (all on anthropic), else "not an API error". retry is True only for RateLimitError, OverloadedError, InternalServerError and APIConnectionError. request_id is e.request_id for an APIStatusError, else None.
Under if __name__ == "__main__":, with a client made with max_retries=0, call lab_faults([{"status": 529}, {"status": 429}]) and ask "claude-haiku-5-5" Is the ambulance paid? twice, then once with the model "claude-haiku-5": print KIND, retry: yes or no, request ID for each. The check also raises a 401, 403, 413, 500, 503, a timeout, a connection error and a bug of your own at it.
- Task 2
with_retries.py: retries, written by hand
Write with_retries(call, tries=4): call() until it succeeds. Retry only a RateLimitError, OverloadedError, InternalServerError or APIConnectionError, at most tries calls in all, then raise the last error; raise anything else at once. Before retry n, wait the error's retry-after header in seconds if it has one, else 0.5 x 2**(n-1) s (at most 8) times a jitter between 0.75 and 1, and print attempt N failed: STATUS TYPE, waiting S s first.
Under if __name__ == "__main__":, with a client made with max_retries=0 and lab_faults([{"status": 529}, {"status": 429, "retryAfter": 1}]), ask "claude-haiku-5-5" (max_tokens 1024): Is the ambulance paid? through with_retries, and print the answer's text.
- Task 3
limits.py: rate limits, and the cache
With the lab at 5,000 input tokens a minute (lab limits itpm=5000) and a client made with max_retries=0, ask the three QUESTIONS (given) with "claude-haiku-5-5", max_tokens 1024, and system as one text block of SYSTEM with "cache_control": {"type": "ephemeral"}, each with client.messages.with_raw_response.create.
Print one line each: QUESTION counted C, read R, remaining M of L, where C is input_tokens + cache_creation_input_tokens, R is cache_read_input_tokens, and M and L are the anthropic-ratelimit-input-tokens-remaining and -limit headers.
- Task 4 · interview question
Interview: broken_stream.py
"A family saw half an answer, then nothing. The SDK retries a 529, so why not this time?" Write stream_answer(question, write) -> str: stream Sahay's answer ("claude-opus-5-5", max_tokens 2048, system=SYSTEM) with client.messages.stream, calling write(text) for each piece of text. If the stream breaks (an APIStatusError whose type is overloaded_error or api_error), write \n[the answer broke off: TYPE. Starting again.]\n and stream the same request again from the start; two attempts in all, then raise. Raise any other error at once. Return the one complete answer's text.
Under if __name__ == "__main__":, call lab_faults([{"status": 529, "midStream": True, "after": 40}]), stream Please write a short note on how Parchi helps families. and print N characters (the answer's length).
What you will learn
- The errors: each HTTP status, its error type, and its exception class in the SDK, most specific first.
- Which to retry: rate limits, overloads, server errors and lost connections can pass; a request the API refused will be refused again.
- The SDK's own retries: max_retries, timeout, retry-after, and the backoff it uses.
- Your own retries: backoff with jitter, written by hand.
- Rate limits: the headers on every reply, and why cached tokens let you stay under an input limit.
- A stream that breaks after it started, which no retry can reach.
More in Cost
Build "Errors, retries and rate limits" yourself
Parchi, a Jaipur startup, helps families claim health insurance. You build Sahay, a claims assistant that reads bills and policies with Claude, and measure what caching, models and effort cost. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Claude and the Anthropic SDK are free. This one comes with the all labs plan.