8.1 - Debugging Claude API Errors

Build exercise: Trigger, diagnose, and correctly handle five different error types

Beginner · 35 minutes

You'll practice:

• Distinguish client-side, auth, and transient errors from their status code and error.type
• Use typed SDK exceptions instead of string matching or a single broad catch
• Apply correct handling for each category: fix-and-resend vs backoff-and-retry

1. Deliberately trigger a 400 (send a request missing max_tokens or with non-alternating message roles) and a 401 (use an obviously fake API key), and print the full error envelope for each - status code, error.type, message, and request_id.

   Seeing the real response shape for each category, including request_id, is more durable than memorising a table of codes.

   You should see: Two distinctly different error.type values (invalid_request_error, authentication_error) with messages that clearly explain each specific problem, plus a logged request_id for each.

   Hints

   1. Never test invalid credentials against a key you actually use elsewhere - use an obviously fake string for the 401 case. What SDK call surfaces the error object's fields directly?

   2. Wrap each call in a try/except, catch the SDK's typed exception, and read e.status_code, e.type, e.message, and e.request_id (or the response envelope directly if you're using raw HTTP).

   3. import anthropic
      client = anthropic.Anthropic(api_key="sk-ant-obviously-fake")
      try:
          client.messages.create(model="claude-opus-5", max_tokens=100, messages=[{"role": "user", "content": "hi"}])
      except anthropic.AuthenticationError as e:
          print(e.status_code, e.type, e.message, e.request_id)

2. Write a most-specific-first exception chain (NotFoundError, RateLimitError, generic APIStatusError, then APIConnectionError) around a real API call, and log a different message for each branch.

   The exam tests whether you branch on typed exceptions in the right order, not whether you can catch 'an error' - a single broad catch discards the retryable/non-retryable distinction.

   You should see: A try/except block with at least four ordered except clauses, each printing a distinguishable log line, with the most specific exception types listed before the general ones.

   Hints

   1. What happens if you put the base APIStatusError clause before RateLimitError in the chain? Does RateLimitError ever get reached?

   2. Order matters: since RateLimitError is a subclass of APIStatusError, it must be caught first or the more general clause swallows it silently.

   3. try:
          client.messages.create(model="claude-opus-5", max_tokens=100, messages=[{"role": "user", "content": "hi"}])
      except anthropic.NotFoundError as e:
          print("bad model/resource:", e.request_id)
      except anthropic.RateLimitError as e:
          print("back off, retry-after:", e.response.headers.get("retry-after"))
      except anthropic.APIStatusError as e:
          print("other status error:", e.status_code, e.type)
      except anthropic.APIConnectionError as e:
          print("network failure, no response received")

3. Trigger a 404 by using a deliberately mistyped model ID, and confirm the SDK does NOT auto-retry it (measure elapsed time or add a print inside a retry hook).

   404, like 400/401/403/413, is excluded from the SDK's automatic retry logic because it's deterministic - retrying it wastes calls and can hide the real typo.

   You should see: A NotFoundError raised on the first attempt with no delay before it - confirming the SDK didn't spend time retrying a request that could never succeed unchanged.

   Hints

   1. Compare how long the call takes to fail versus how long a 429/5xx retry sequence would take. What should the difference tell you?

   2. Time the call with a simple before/after timestamp. A 404 should fail almost immediately; a retried 429/5xx would show multi-second delays from the exponential backoff.

   3. import time
      start = time.time()
      try:
          client.messages.create(model="claude-sonnet-4-99-typo", max_tokens=100, messages=[{"role": "user", "content": "hi"}])
      except anthropic.NotFoundError as e:
          print(f"failed in {time.time() - start:.2f}s -- no retry delay, as expected")

4. Implement a custom exponential backoff wrapper (base delay, jitter, respecting retry-after when present) around a function, but only apply it to RateLimitError and 5xx errors - never to 400/401/403/404.

   This is the core exam distinction in code form: retryable transient failures get backoff, deterministic client failures get re-raised immediately so the caller can fix the actual problem.

   You should see: A function that retries up to N times with increasing delay on RateLimitError/InternalServerError, but immediately re-raises (does not retry) BadRequestError, AuthenticationError, PermissionDeniedError, or NotFoundError.

   Hints

   1. Which exceptions should hit 'raise' immediately inside your except block, and which should sleep and loop again?

   2. Catch the non-retryable types first and re-raise without delay. Catch RateLimitError and APIStatusError with status_code >= 500 last, and only those branches sleep before looping.

   3. import time, random
      def call_with_backoff(client, max_retries=4, base=1.0, **kwargs):
          for attempt in range(max_retries):
              try:
                  return client.messages.create(**kwargs)
              except (anthropic.BadRequestError, anthropic.AuthenticationError,
                      anthropic.PermissionDeniedError, anthropic.NotFoundError):
                  raise  # non-retryable -- fix the request, don't resend it
              except anthropic.RateLimitError as e:
                  retry_after = e.response.headers.get("retry-after")
                  delay = float(retry_after) if retry_after else base * (2 ** attempt) + random.uniform(0, 1)
                  time.sleep(delay)
              except anthropic.APIStatusError as e:
                  if e.status_code < 500:
                      raise
                  time.sleep(base * (2 ** attempt) + random.uniform(0, 1))
          raise RuntimeError("exhausted retries")

5. Send a request with a deliberately invalid tool input_schema (e.g. a required field name that doesn't exist in properties) and confirm you can pinpoint the exact schema problem from the error message alone, without reading the model's output.

   Tool-calling 400s are one of the most common real-world debugging scenarios, and the exam specifically tests whether you know the model never ran, so nothing about model behaviour explains the failure.

   You should see: A BadRequestError whose message names the specific schema defect (an unknown key, a malformed type, or a required field with no matching property) rather than anything about the model's reasoning.

   Hints

   1. Where does the model appear in the request lifecycle relative to schema validation - before or after? What does that imply about who caused the 400?

   2. Schema validation happens before the model is invoked at all, so the message will point at the schema definition itself, not at any generated content.

   3. bad_tool = {
          "name": "get_weather",
          "description": "Get the weather",
          "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["location"]}
      }
      try:
          client.messages.create(model="claude-opus-5", max_tokens=100, tools=[bad_tool],
              messages=[{"role": "user", "content": "weather in Paris?"}])
      except anthropic.BadRequestError as e:
          print(e.message)  # names the schema problem directly