CertSafari
    Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards· Lessons

    Domain 2 · Lesson 7/24

    Claude API integration resilience: error classes, streaming, and file ingestion

    Integration Resilience

    16 min read
    5% of exam
    4 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Classify a Claude API error by HTTP status and error.type, and decide whether to retry, wait, or fix the request
    • Diagnose duplicated traffic caused by stacking a custom retry loop on top of the SDK's built-in retries
    • Read stop_reason and mid-stream errors from the correct server-sent events in a streaming response
    • Route each file type to the correct content block and correct oversized or mismatched Files API requests

    Key concept

    Error class decides the recovery — Every Claude API failure carries a status code and an error.type, and the type tells you the recovery. Some errors clear if you wait. Some need the request changed. Some say the request was never processed at all. A resilient integration branches on that class and never retries everything the same way.

    1.Error classes and what each one means for a retry

    An integration with the Claude API fails in a few distinct ways. Only some of them clear up if you send the same request again. Every error response is JSON with an error.type and a message, plus a request_id to give support. The status code is a rough first sort, and the type is the precise one. Retry logic that ignores the class does one of two harmful things: it hammers an endpoint that will never accept the request, or it gives up on a failure that would have cleared in a second.

    Claude API error classes and the correct client response
    StatusError typeRetry the identical request?Correct action
    400invalid_request_errorNoFix the format or content of the request. This status is also returned when a spend limit you set is reached.
    401 / 403authentication_error / permission_errorNoFix the key, or the key's access to the workspace and resource.
    404not_found_errorNoCheck the endpoint path and the resource IDs in the URL.
    413request_too_largeNoShrink the request below the endpoint's byte limit.
    429rate_limit_errorOnly when retry-after is presentWait the retry-after seconds. A spend-cap 429 keeps failing until access resumes.
    500api_errorYes, with exponential backoffIf it persists, contact support with the request ID.
    500 / 504timeout_errorNot as-isUse the streaming Messages API for long-running requests.
    529overloaded_errorYes, with backoffThe API is temporarily overloaded.

    Two of these rows are traps. The first is 429. A normal rate limit means you exceeded RPM, input tokens per minute, or output tokens per minute. The response tells you which one, and when it includes a retry-after header you wait that many seconds. A 429 also comes back once the organization reaches its usage tier's monthly spend cap. That response has the same rate_limit_error type but no retry-after header, and it carries error.details.error_code set to enforced_spend_limit_reached. Retrying it achieves nothing until the next month begins or the tier is raised. A spend limit that you configured yourself shows up differently again: a 400 invalid_request_error whose message says when access resumes.

    The second trap is timeout_error, which can arrive with more than one status code. A 500 can carry it when a request reaches the server's time limit before the response starts. Reading only the status would put that request in the 'retry with backoff' bucket, and the next identical request would time out the same way. The fix is structural: send long requests with streaming.

    In code, this classification comes from the SDK's typed exceptions. A 404, for example, surfaces as anthropic.NotFoundError. Catch the most specific classes first and don't match on message text. New type values can appear under the versioning policy, so treat unrecognized types as non-retryable by default.

    Checkpoint 1 of 9· Match them up

    Match each error response to the client action that the error semantics call for.

    Tap a term, then the definition that fits it.

    Checkpoint 2 of 9· Check yourself

    A batch job's retry wrapper keeps receiving HTTP 429 with error.type rate_limit_error. The response has no retry-after header, and error.details.error_code is enforced_spend_limit_reached. What should the integration do?

    Sources12

    2.Layered retries multiply traffic

    The official SDK already does the transient-error retrying that teams often write themselves. It retries connection errors, rate limits and 5xx server errors with exponential backoff. By default it makes two retries per call, and it honors retry-after when the header is present. It does not retry a 400 or a 404, because nothing about waiting would make those succeed.

    The fix is to keep one retry layer. Either set max_retries on the client to the budget you want, or delete the helper's retry loop and let the SDK handle transient failures. Keep an outer layer only for decisions the SDK can't make, such as switching to a fallback after retries run out. Even then, set the client to max_retries=0 inside that layer so the two budgets don't multiply. The API does not replay failed requests on the server side, so every extra request comes from the client.

    Checkpoint 3 of 9· Check yourself

    During a 5xx incident, logs show that each failing logical call sends exactly 15 HTTP requests, and unrelated jobs in the organization start receiving 429s. The service wraps a default-configured official SDK client in a helper that makes up to five attempts. Which change fixes the defect?

    Checkpoint 4 of 9· Exam question

    A team wraps the official SDK client in their own retry helper that makes up to six attempts. During an incident, one failing call produces around eighteen HTTP requests and trips rate limits for other jobs. What explains this, and what is the fix?

    Sources1

    3.Streaming event order and terminal-event semantics

    A streamed response arrives as a sequence of named server-sent events in a fixed grammar. A client that reads a field from the wrong event gets an empty value, not an error. The sequence is:

    1. message_start, which holds a Message object with empty content
    2. For each content block: content_block_start, any number of content_block_delta events, then content_block_stop
    3. One or more message_delta events that carry top-level changes to the final Message
    4. A final message_stop

    ping events can appear anywhere in the stream. New event types may be added, so a client that crashes on an unrecognized event name is fragile.

    The opening event: stop_reason is null because nothing has been generated yettext
    event: message_start
    data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}
    The closing events: stop_reason arrives in message_delta, and message_stop carries nothing but its typetext
    event: message_delta
    data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}
    
    event: message_stop
    data: {"type": "message_stop"}

    Once you have the value from message_delta, act on it the same way as for a non-streamed response. What each value means is covered under stop reasons. The cumulative usage.output_tokens also arrives in message_delta, so a cost log written at message_start is wrong too.

    Tool calls stream their arguments in pieces. A tool_use block's deltas are input_json_delta events, and each one holds a partial_json string fragment such as {"location":. Fragments are not valid JSON on their own. Passing each one to a JSON parser throws on the first delta. The correct pattern is to append the strings and parse once at that block's content_block_stop, or to use the SDK's streaming helpers, which do the accumulation for you.

    A stream can also fail after it has started successfully. The HTTP status was already 200 when the first byte arrived, so a failure that happens later comes back as an error event in the body:

    An error delivered inside an already-successful streamtext
    event: error
    data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

    This overloaded_error is the in-stream form of what would be an HTTP 529 without streaming. Retry logic that only inspects the status code never sees it, and the response just ends early. The event loop has to handle error events itself and treat a stream that ends without message_stop as incomplete.

    Streaming is also the fix for long requests that time out. The SDK refuses non-streaming Messages requests that it expects to run past a 10-minute timeout, and some networks drop idle connections before a long non-streamed response arrives. If you don't need incremental output, client.messages.stream(...) combined with stream.get_final_message() keeps the connection active and returns the same Message object that create() would.

    Checkpoint 5 of 9· Put it in order

    You're writing a direct SSE parser for a streamed reply that has one text block. Put the events it should receive in order, ignoring ping events.

    1. 1.content_block_delta events, each carrying a text_delta fragment
    2. 2.message_start, which holds a Message with empty content and a null stop_reason
    3. 3.message_stop, which carries only its type
    4. 4.message_delta, which carries the final stop_reason and cumulative output_tokens
    5. 5.content_block_stop for index 0
    6. 6.content_block_start for the text block at index 0

    Checkpoint 6 of 9· Check yourself

    Under heavy load, some streamed replies in a chat service stop partway through. Every one of them returned HTTP 200, and the retry wrapper, which checks only the status code, never fires. What is the defect and its fix?

    Checkpoint 7 of 9· Exam question

    A support chatbot streams a reply and logs the stop reason when the first message_start event arrives. Every log line shows null, so the dashboard can't tell truncated replies (max_tokens) from complete ones. What is the correct fix?

    Sources31

    4.Multi-format ingestion through the Files API

    Ingestion pipelines fail in ways the retry logic cannot fix, because the defect is in the request itself. Every endpoint has a maximum request size. Messages accepts 128 MB, Batch 256 MB and Files 500 MB. Above the limit the response is a 413 request_too_large. On the first-party API, Cloudflare returns it before the request reaches the API servers. Sending the same bytes again, with or without jitter, gets the same 413. Splitting a base64 document across two user messages doesn't help either, because both messages are still in the same request body.

    The fix for a large document is to upload it once through the Files API and refer to it by ID. A 140 MB scanned PDF is too big to embed in a Messages request but fits under the 500 MB per-file limit. You upload it once and get back a file_id. Each later request then refers to that ID instead of re-sending the bytes:

    Uploading a PDF once to get a reusable file_idpython
    uploaded = client.files.upload(
        file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
    )
    file_id = uploaded.id
    print(file_id)

    The file_id only works in a content block that matches the file's type. A pipeline that puts every upload into a document block works for PDFs and gets a 400 for every screenshot.

    Choosing the content block for a file_id by file type
    File typeMIME typeContent blockUse
    PDFapplication/pdfdocumentText analysis, document processing
    Plain texttext/plaindocumentText analysis, processing
    Imagesimage/jpeg, image/png, image/gif, image/webpimageImage analysis, visual tasks
    Datasets, othersVariescontainer_uploadData analysis with the code execution tool

    Other Files API errors each point to a specific fix:

    • 400, exceeds context window: a file can be within the upload limit and still be too large to read as tokens. A 300 MB CSV in a document block fails this way. If the goal is computation, such as quarterly totals, upload it for the code execution tool with a container_upload block.
    • 400, not downloadable: files you upload come back with "downloadable": false. Only files created by skills or the code execution tool can be downloaded, so archive uploads from your own copy, not by calling the content endpoint.
    • 404, file not found: the file_id doesn't exist, is outside your workspace, or has passed its expires_at. A Messages request that references an expired file fails before inference.
    • Unsupported formats: .docx and .xlsx can't go in a document block. Convert them to plain text and put the content directly in the message.

    Checkpoint 8 of 9· Fill the gap

    A 140 MB scanned PDF embedded as base64 in a Messages request keeps returning 413 request_too_large. The fix is to send the bytes once and refer to them by file_id in later requests. Which method completes this sample?

    uploaded = client.files. ? (
        file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
    )
    file_id = uploaded.id
    print(file_id)

    Checkpoint 9 of 9· Exam question

    An ingestion service base64-embeds a 140 MB scanned PDF in a Messages request and gets a 413 request_too_large. The retry wrapper repeats the identical call and fails each time. What should the developer do?

    Sources14

    Sources

    (4)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Retry the request with exponential backoff; if the error persists, contact support with the request ID.”
      ↩︎ Error classes and what each one means for a retry
      “such as a 500 when a request reaches the server’s time limit before the response starts”
      ↩︎ Error classes and what each one means for a retry
      “Catch the SDK’s typed classes rather than string-matching error messages, handling the most specific classes first.”
      ↩︎ Error classes and what each one means for a retry
      “automatically retries transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default”
      ↩︎ Layered retries multiply traffic
      “The SDK client accepts max_retries to configure or disable this behavior.”
      ↩︎ Layered retries multiply traffic
      “an error can occur after the API returns a 200 response. In that case, error handling doesn’t follow these standard mechanisms.”
      ↩︎ Streaming event order and terminal-event semantics
      “The Anthropic SDK validates that your non-streaming Messages API requests are not expected to exceed a 10-minute timeout.”
      ↩︎ Streaming event order and terminal-event semantics
      “If you exceed these limits, you’ll receive a 413 request_too_large error.”
      ↩︎ Multi-format ingestion through the Files API
      “a top-level error object that always includes a type and message value”
      ↩︎ Key concept
      “A tier spend-cap 429 has no retry-after header and keeps failing until access resumes”
      ↩︎ Exam trap 2
      “The SDK client accepts max_retries to configure or disable this behavior.”
      ↩︎ Exam trap 3
      “If you exceed these limits, you’ll receive a 413 request_too_large error.”
      ↩︎ Exam trap 4
      “The API also returns timeout_error with other status codes, such as a 500 when a request reaches the server’s time limit before the response starts.”
      ↩︎ Checkpoint
      “A tier spend-cap 429 has no retry-after header and keeps failing until access resumes”
      ↩︎ Checkpoint
      “The official SDK automatically retries transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default”
      ↩︎ Checkpoint
      “When receiving a streaming response over server-sent events (SSE), an error can occur after the API returns a 200 response.”
      ↩︎ Checkpoint
    2. 2.
      “When the response has a retry-after header, wait that many seconds before retrying.”
      ↩︎ Error classes and what each one means for a retry
      “Use it to tell this response apart from a rate limit.”
      ↩︎ Error classes and what each one means for a retry
      “When usage reaches a spend limit you set, requests return HTTP 400 with error type invalid_request_error.”
      ↩︎ Error classes and what each one means for a retry
    3. 3.
      “message_start: contains a Message object with empty content.”
      ↩︎ Streaming event order and terminal-event semantics
      “your code should handle unknown event types gracefully.”
      ↩︎ Streaming event order and terminal-event semantics
      “You can accumulate the string deltas and parse the JSON once you receive a content_block_stop event”
      ↩︎ Streaming event order and terminal-event semantics
      “you might receive an overloaded_error, which would normally correspond to an HTTP 529 in a non-streaming context”
      ↩︎ Streaming event order and terminal-event semantics
      “One or more message_delta events, indicating top-level changes to the final Message object.”
      ↩︎ Exam trap 1
      “One or more message_delta events, indicating top-level changes to the final Message object.”
      ↩︎ Prediction
      “each of which has a content_block_start, any number of content_block_delta events, and a content_block_stop event”
      ↩︎ Checkpoint
    4. 4.
      “Once uploaded, reference the file by passing the id from the upload response as file_id:”
      ↩︎ Multi-format ingestion through the Files API
      “Invalid file type (400): The file type doesn’t match the content block type (for example, using an image file in a document block).”
      ↩︎ Multi-format ingestion through the Files API
      “Exceeds context window size (400): The file is larger than the context window size”
      ↩︎ Multi-format ingestion through the Files API
      “To analyze datasets instead of reading them as text, upload them for the code execution tool using a container_upload block”
      ↩︎ Multi-format ingestion through the Files API
      “Files you upload cannot be downloaded.”
      ↩︎ Multi-format ingestion through the Files API
      “A Messages request that references the file fails before inference.”
      ↩︎ Multi-format ingestion through the Files API
      “convert the files to plain text and include the content directly in your message”
      ↩︎ Multi-format ingestion through the Files API

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.