Streaming a response, properly

Written by a person. Last read by a person on 2026-09-04, 4 days ago. Its facts were checked by the eval suite on 2026-09-07.

You are about to make your first call to this API, you are moving code over from another provider and want to know what will bite you, or something is failing and you do not yet know which page you need.

This covers one workflow of the Claude API and covers it properly: streaming a response, with error handling, retries, and rate-limit backoff that behave under real conditions.

It is deliberately not a survey. A survey of twenty endpoints is easier to write and easier to skim, and it will not tell you the thing that actually costs you a weekend, which is what happens when the connection drops halfway through a response you have already half-rendered.

Pick your on-ramp

The two are genuinely different documents, and reading the wrong one wastes your time in a way that is hard to notice.

I have not used an LLM API before

Start with your first streamed request. It builds the model from nothing: what a token is in billing terms, why responses arrive in pieces, and what the pieces are.

I am coming from another provider's API

Start here, on this page, and read the next section before anything else. Then go to the quickstart.

The mechanics will feel familiar enough that you will skip the explanation, and the place where your existing model breaks is not somewhere you will be looking.

If you are switching: what your existing model gets wrong

You are carrying a model of "streaming an LLM response" that is right about the shape and wrong about three specifics. Each of them fails quietly rather than loudly.

You expect the stream to be a stream of text

It is a stream of typed events, and text is one of the things that arrives in them. A response can also carry thinking blocks and tool-use blocks, interleaved, each with its own start, deltas, and stop.

What breaks: code that concatenates every delta it sees produces output with reasoning spliced into the middle of the answer. It looks like the model rambled. It did not; you concatenated two different channels.

Handle the event types, or use the SDK helper that accumulates them for you and hand back the final message.

You expect an HTTP error to mean the request failed

For non-streaming requests it does. Once you are streaming, the status code is decided before the response body exists. The API returns 200, starts sending events, and can then send an error event partway through.

What breaks: a try/except around the request that has already returned successfully. Your error handling is in the wrong place, it never fires, and a truncated response is indistinguishable from a complete one to everything downstream. The live docs are explicit that mid-stream errors do not follow the standard mechanism.

Handle errors inside the loop as well as around it.

You expect a 429 to mean "wait and try again"

Usually it does, and the response tells you exactly how long to wait in a header. Not every 429 is a rate limit. When an organization reaches its tier's monthly spend cap, the API returns 429 with the same rate_limit_error type, no wait header at all, and it keeps returning it until the calendar month rolls over.

What breaks: a retry loop that treats every 429 the same. It waits, retries, fails, waits longer, retries, fails, and burns its whole budget of attempts against a condition that will not change for three weeks. Worse, it does this quietly, because retrying a 429 looks like correct behavior.

Distinguishing the two is its own section, and it is the single most useful thing on this site if you are shipping something that runs unattended.

Where each page sits

flowchart TD
  S[Switching from another API] --> M[The three transfer misconceptions]
  N[New to LLM APIs] --> Q
  M --> Q[Quickstart: one streamed request]
  Q --> R[Retries and rate-limit backoff]
  R --> T[Troubleshooting by error family]
  R --> F[Parameter reference]
  T --> F

What this documentation promises

Every fact about the API on these pages is verified against Anthropic's live documentation at authoring time, recorded with its source URL and the date it was checked, and re-checked by an eval suite that fails the build when prose and the data layer disagree.

That is not a claim about care. It is a mechanism, and you can run it yourself.