> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming

The OpenRouter API allows streaming responses from *any model*. This is useful for building chat interfaces or other applications where the UI should update as the model generates the response.

To enable streaming, you can set the `stream` parameter to `true` in your request. The model will then stream the response to the client in chunks, rather than returning the entire response at once.

Here is an example of how to stream a response, and process it:

```typescript title="TypeScript SDK" expandable lines theme={null}
import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const question = 'How would you build the tallest building ever?';

const stream = await openRouter.responses.send({
  responsesRequest: {
    model: 'openai/gpt-4o',
    input: question,
    stream: true,
  },
});

if (!(stream instanceof ReadableStream)) {
  throw new Error('Expected a streaming response');
}

for await (const event of stream) {
  if (event.type === 'response.failed') {
    throw new Error(event.response.error?.message ?? 'Response failed');
  }
  if (event.type === 'response.incomplete') {
    throw new Error(
      `Response incomplete: ${event.response.incompleteDetails?.reason ?? 'unknown reason'}`,
    );
  }

  if (event.type === 'response.output_text.delta') {
    console.log(event.delta);
  }

  // The final response.completed event includes usage stats
  if (event.type === 'response.completed') {
    console.log('Usage:', event.response.usage);
  }
}
```

```python Python expandable lines theme={null}
import requests
import json

question = "How would you build the tallest building ever?"

url = "https://openrouter.ai/api/v1/responses"
headers = {
  "Authorization": f"Bearer <OPENROUTER_API_KEY>",
  "Content-Type": "application/json"
}

payload = {
  "model": "openai/gpt-4o",
  "input": question,
  "stream": True
}

buffer = ""
with requests.post(url, headers=headers, json=payload, stream=True) as r:
  r.raise_for_status()
  for chunk in r.iter_content(chunk_size=1024, decode_unicode=True):
    buffer += chunk
    while True:
      # Find the next complete SSE line
      line_end = buffer.find('\n')
      if line_end == -1:
        break

      line = buffer[:line_end].strip()
      buffer = buffer[line_end + 1:]

      # Skip SSE comments (lines starting with ":"), e.g. the
      # ": OPENROUTER PROCESSING" keep-alive — they are not JSON
      if line.startswith(':'):
        continue
      if not line.startswith('data: '):
        continue

      data = line[6:]
      if data == '[DONE]':
        break

      try:
        data_obj = json.loads(data)
      except json.JSONDecodeError:
        continue

      if data_obj.get("type") == "response.failed":
        error = data_obj["response"].get("error") or {}
        raise RuntimeError(error.get("message", "Response failed"))
      if data_obj.get("type") == "response.incomplete":
        details = data_obj["response"].get("incomplete_details") or {}
        raise RuntimeError(f"Response incomplete: {details.get('reason', 'unknown reason')}")
      if data_obj.get("type") == "response.output_text.delta":
        print(data_obj["delta"], end="", flush=True)
```

```typescript title="TypeScript (fetch)" expandable lines theme={null}
const question = 'How would you build the tallest building ever?';
const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    input: question,
    stream: true,
  }),
});

const reader = response.body?.getReader();
if (!reader) {
  throw new Error('Response body is not readable');
}

const decoder = new TextDecoder();
let buffer = '';

try {
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    // Append new chunk to buffer
    buffer += decoder.decode(value, { stream: true });

    // Process complete lines from buffer
    while (true) {
      const lineEnd = buffer.indexOf('\n');
      if (lineEnd === -1) break;

      const line = buffer.slice(0, lineEnd).trim();
      buffer = buffer.slice(lineEnd + 1);

      // Skip SSE comments (lines starting with ":"), e.g. the
      // ": OPENROUTER PROCESSING" keep-alive — they are not JSON
      if (line.startsWith(':')) continue;

      if (line.startsWith('data: ')) {
        const data = line.slice(6);
        if (data === '[DONE]') break;

        try {
          const parsed = JSON.parse(data);
          if (parsed.type === 'response.failed') {
            throw new Error(parsed.response.error?.message ?? 'Response failed');
          }
          if (parsed.type === 'response.incomplete') {
            throw new Error(
              `Response incomplete: ${parsed.response.incomplete_details?.reason ?? 'unknown reason'}`,
            );
          }
          if (parsed.type === 'response.output_text.delta') {
            console.log(parsed.delta);
          }
        } catch (error) {
          if (error instanceof SyntaxError) continue;
          throw error;
        }
      }
    }
  }
} finally {
  reader.cancel();
}

```

```go title="Go" lines theme={null}
package main

import (
	"bufio"
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	question := "How would you build the tallest building ever?"

	body, _ := json.Marshal(map[string]any{
		"model":  "openai/gpt-4o",
		"input":  question,
		"stream": true,
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		b, _ := io.ReadAll(resp.Body)
		log.Fatalf("HTTP %d: %s", resp.StatusCode, b)
	}

	scanner := bufio.NewScanner(resp.Body)
	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
	for scanner.Scan() {
		data, ok := strings.CutPrefix(scanner.Text(), "data: ")
		if !ok || data == "[DONE]" {
			continue
		}
		var event struct {
			Type     string `json:"type"`
			Delta    string `json:"delta"`
			Response struct {
				Error             *struct{ Message string } `json:"error"`
				IncompleteDetails *struct{ Reason string }  `json:"incomplete_details"`
				Usage             json.RawMessage           `json:"usage"`
			} `json:"response"`
		}
		if err := json.Unmarshal([]byte(data), &event); err != nil {
			continue
		}

		switch event.Type {
		case "response.failed":
			msg := "Response failed"
			if event.Response.Error != nil {
				msg = event.Response.Error.Message
			}
			log.Fatal(msg)
		case "response.incomplete":
			reason := "unknown reason"
			if event.Response.IncompleteDetails != nil {
				reason = event.Response.IncompleteDetails.Reason
			}
			log.Fatalf("Response incomplete: %s", reason)
		case "response.output_text.delta":
			fmt.Println(event.Delta)
		case "response.completed":
			// The final response.completed event includes usage stats
			fmt.Println("Usage:", string(event.Response.Usage))
		}
	}
	if err := scanner.Err(); err != nil {
		log.Fatal(err)
	}
}

```

```bash title="cURL" lines theme={null}
curl -sSfN https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "How would you build the tallest building ever?",
    "stream": true
  }' |
  # jq does the filtering: sed and grep would hold the text back until the stream ends
  jq -R --unbuffered -r 'select(startswith("data: ")) | .[6:] | select(. != "[DONE]") | fromjson |
    if .type == "response.failed" then error(.response.error.message // "Response failed")
    elif .type == "response.incomplete" then error("Response incomplete: " + (.response.incomplete_details.reason // "unknown reason"))
    elif .type == "response.output_text.delta" then .delta
    # The final response.completed event includes usage stats
    elif .type == "response.completed" then "Usage: " + (.response.usage | tostring)
    else empty end'

```

```text title="Output" theme={null}
Building
 the
 tallest
 building
 ever
 would
 be
 an
 incredibly
 ambitious
 and
 complex
 endeavor
,
 requiring
 careful
 consideration
 of
 engineering
,
 materials
,
 sustainability
,
 and
 cost
.
 Here's
 a
 broad
 overview
 of
 the
 factors
 you
 would
 need
 to
 consider
:
```

### Additional information

For SSE (Server-Sent Events) streams, OpenRouter occasionally sends comments to prevent connection timeouts. These comments look like:

```text lines theme={null}
: OPENROUTER PROCESSING
```

Comment payload can be safely ignored per the [SSE specs](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation). However, you can use it to improve UX as needed, e.g. by showing a dynamic loading indicator.

> [!WARNING]
>
> If you parse the stream by hand, skip lines that start with `:` before calling `JSON.parse`. Passing a comment line like `: OPENROUTER PROCESSING` to `JSON.parse` throws, and unhandled it will crash your stream loop. The snippets above handle this.

A spec-compliant parser such as [eventsource-parser](https://github.com/rexxars/eventsource-parser) handles comments, multi-line `data:` fields, and buffering for you:

```typescript title="eventsource-parser" expandable lines theme={null}
import { createParser } from 'eventsource-parser';

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    input: 'Hello',
    stream: true,
  }),
});

// Errors that occur before streaming starts are plain JSON, not SSE
if (!response.ok) {
  const error = await response.json();
  throw new Error(error.error.message);
}

const parser = createParser({
  onEvent(event) {
    if (event.data === '[DONE]') return;
    try {
      const data = JSON.parse(event.data);
      if (data.type === 'response.output_text.delta') {
        console.log(data.delta);
      }
    } catch {
      // Ignore invalid JSON
    }
  },
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  parser.feed(decoder.decode(value, { stream: true }));
}
```

```python title="Python" lines theme={null}
import json
import os

import requests

response = requests.post(
    "https://openrouter.ai/api/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-4o",
        "input": "Hello",
        "stream": True,
    },
    stream=True,
)

# Errors that occur before streaming starts are plain JSON, not SSE
if not response.ok:
    raise RuntimeError(response.json()["error"]["message"])

response.encoding = "utf-8"
data_lines = []
for line in response.iter_lines(decode_unicode=True):
    if line.startswith(":"):
        continue  # SSE comment, e.g. ": OPENROUTER PROCESSING"
    if line.startswith("data:"):
        data_lines.append(line[5:].removeprefix(" "))
        continue
    if line or not data_lines:
        continue
    # A blank line ends the event; join multi-line data: fields
    data, data_lines = "\n".join(data_lines), []
    if data == "[DONE]":
        continue
    try:
        event = json.loads(data)
    except json.JSONDecodeError:
        continue  # Ignore invalid JSON
    if event.get("type") == "response.output_text.delta":
        print(event["delta"])

```

```go title="Go" lines theme={null}
package main

import (
	"bufio"
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
)

func handleEvent(data string) {
	if data == "" || data == "[DONE]" {
		return
	}
	var event struct {
		Type  string `json:"type"`
		Delta string `json:"delta"`
	}
	if err := json.Unmarshal([]byte(data), &event); err != nil {
		return // Ignore invalid JSON
	}
	if event.Type == "response.output_text.delta" {
		fmt.Println(event.Delta)
	}
}

func main() {
	body, _ := json.Marshal(map[string]any{
		"model":  "openai/gpt-4o",
		"input":  "Hello",
		"stream": true,
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	// Errors that occur before streaming starts are plain JSON, not SSE
	if resp.StatusCode != http.StatusOK {
		var e struct {
			Error struct {
				Message string `json:"message"`
			} `json:"error"`
		}
		json.NewDecoder(resp.Body).Decode(&e)
		log.Fatal(e.Error.Message)
	}

	// Spec-compliant SSE parsing: skip comments, join multi-line data fields,
	// and dispatch each event on a blank line
	var data []string
	scanner := bufio.NewScanner(resp.Body)
	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
	for scanner.Scan() {
		line := scanner.Text()
		switch {
		case line == "":
			handleEvent(strings.Join(data, "\n"))
			data = nil
		case strings.HasPrefix(line, ":"):
			// Comment, e.g. ": OPENROUTER PROCESSING"
		default:
			if v, ok := strings.CutPrefix(line, "data:"); ok {
				data = append(data, strings.TrimPrefix(v, " "))
			}
		}
	}
	handleEvent(strings.Join(data, "\n"))
	if err := scanner.Err(); err != nil {
		log.Fatal(err)
	}
}

```

```bash title="cURL" lines theme={null}
curl -sSfN https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Hello",
    "stream": true
  }' |
  # Keep only data: lines; comment lines such as ": OPENROUTER PROCESSING" are dropped.
  # Ignore invalid JSON (including [DONE]) and print text deltas. jq does the filtering:
  # sed and grep would hold the text back until the stream ends
  jq -R --unbuffered -r 'select(startswith("data: ")) | .[6:] | fromjson? | select(.type == "response.output_text.delta") | .delta'
```

```text title="Output" theme={null}
Hi
 there
!
 How
 can
 I
 assist
 you
 today
?
```

A parser only handles the SSE framing. Errors that occur mid-generation still arrive as regular `data:` events (a `response.failed` or `error` event). See [Handling Errors During Streaming](#handling-errors-during-streaming) below.

The generation ID is returned in the `X-Generation-Id` response header for all endpoints (chat completions, completions, responses, and messages), which can be useful for debugging and correlating requests.

Some SSE client implementations might not parse the payload according to spec, which leads to an uncaught error when you `JSON.stringify` the non-JSON payloads. We recommend the following clients:

* [eventsource-parser](https://github.com/rexxars/eventsource-parser)
* [OpenAI SDK](https://www.npmjs.com/package/openai)
* [Vercel AI SDK](https://www.npmjs.com/package/ai)

### The final usage chunk (Chat Completions)

On the Chat Completions endpoint (`/api/v1/chat/completions`), every stream ends with an extra chunk that carries the `usage` object for the request, sent just before the `[DONE]` message. OpenAI's spec emits this chunk with an empty `choices` array, but many clients crash when accessing `choices[0].delta` on it, so OpenRouter intentionally deviates: the usage chunk contains one choice with a content-free `delta` that repeats the `finish_reason` (and `native_finish_reason`) of the stream.

```text lines theme={null}
data: {"id":"gen-abc123",...,"choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":"stop","native_finish_reason":"stop"}]}
data: {"id":"gen-abc123",...,"choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":"stop","native_finish_reason":"stop"}],"usage":{...}}
data: [DONE]
```

This means the terminal `finish_reason` appears twice: once on the last content-bearing chunk and again on the usage chunk. Clients that validate streams should treat the usage chunk as an accounting frame rather than a second terminal event.

This shape is specific to Chat Completions. Other endpoints follow their own specs: the Responses API (`/api/v1/responses`) reports usage in the `response.completed` event, and the Messages API (`/api/v1/messages`) reports it in the `message_delta` event before `message_stop`.

### Stream cancellation

Streaming requests can be cancelled by aborting the connection. For supported providers, this immediately stops model processing and billing.

> [accordion] Provider Support
>
> **Supported**
>
> * OpenAI, Azure, Anthropic
> * Fireworks, Mancer, Recursal
> * AnyScale, Lepton, OctoAI
> * Novita, DeepInfra, Together
> * Cohere, Hyperbolic, Infermatic
> * Avian, XAI, Cloudflare
> * SFCompute, Nineteen, Liquid
> * Friendli, Chutes, DeepSeek
>
> **Not Currently Supported**
>
> * AWS Bedrock, Groq, Modal
> * Google, Google AI Studio, Minimax
> * HuggingFace, Replicate, Perplexity
> * Mistral, AI21, Featherless
> * Lynn, Lambda, Reflection
> * SambaNova, Inflection, ZeroOneAI
> * AionLabs, Alibaba, Nebius
> * Kluster, Targon, InferenceNet

To implement stream cancellation:

```typescript title="TypeScript SDK" expandable lines theme={null}
import { OpenRouter } from '@openrouter/sdk';
import { RequestAbortedError } from '@openrouter/sdk/models/errors';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const controller = new AbortController();

try {
  const stream = await openRouter.responses.send({
    responsesRequest: {
      model: 'openai/gpt-4o',
      input: 'Write a story',
      stream: true,
    },
  }, {
    signal: controller.signal,
  });

  if (!(stream instanceof ReadableStream)) {
    throw new Error('Expected a streaming response');
  }

  for await (const event of stream) {
    if (event.type === 'response.output_text.delta') {
      console.log(event.delta);
    }
  }
} catch (error) {
  // Aborting before the response arrives throws RequestAbortedError; aborting mid-stream throws AbortError.
  if (error instanceof RequestAbortedError || (error instanceof Error && error.name === 'AbortError')) {
    console.log('Stream cancelled');
  } else {
    throw error;
  }
}

// To cancel the stream:
controller.abort();
```

```python Python expandable lines theme={null}
import json
import time
import requests
from threading import Event, Thread

def stream_with_cancellation(prompt: str, cancel_event: Event):
    with requests.Session() as session:
        response = session.post(
            "https://openrouter.ai/api/v1/responses",
            headers={"Authorization": f"Bearer <OPENROUTER_API_KEY>"},
            json={"model": "openai/gpt-4o", "input": prompt, "stream": True},
            stream=True
        )
        # An HTTP error (for example a 401) is plain JSON, not an event stream
        if not response.ok:
            print(f"Request failed: {response.status_code} {response.text}")
            response.close()
            return
        response.encoding = "utf-8"

        try:
            for line in response.iter_lines(decode_unicode=True):
                if cancel_event.is_set():
                    print("\nStream cancelled")
                    return
                if not line or not line.startswith("data: "):
                    continue  # Skip blank lines and SSE comments
                data = line[6:]
                if data == "[DONE]":
                    continue
                try:
                    event = json.loads(data)
                except json.JSONDecodeError:
                    continue  # Ignore invalid JSON
                if event.get("type") == "response.output_text.delta":
                    print(event["delta"], end="", flush=True)
        finally:
            response.close()

# Example usage:
cancel_event = Event()
stream_thread = Thread(target=lambda: stream_with_cancellation("Write a story", cancel_event))
stream_thread.start()

# To cancel the stream (here, after 2 seconds):
time.sleep(2)
cancel_event.set()
stream_thread.join()

```

```typescript title="TypeScript (fetch)" expandable lines theme={null}
const controller = new AbortController();

// To cancel the stream (here, after 2 seconds):
setTimeout(() => controller.abort(), 2000);

try {
  const response = await fetch(
    'https://openrouter.ai/api/v1/responses',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer <OPENROUTER_API_KEY>`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'openai/gpt-4o',
        input: 'Write a story',
        stream: true,
      }),
      signal: controller.signal,
    },
  );

  // An HTTP error (for example a 401) is plain JSON, not an event stream
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status} ${await response.text()}`);
  }

  // Process the stream, printing text deltas as they arrive
  const reader = response.body!.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop() ?? '';
    for (const line of lines) {
      if (!line.startsWith('data: ')) continue;
      const data = line.slice(6);
      if (data === '[DONE]') continue;
      try {
        const event = JSON.parse(data);
        if (event.type === 'response.output_text.delta') {
          process.stdout.write(event.delta);
        }
      } catch {
        // Ignore invalid JSON
      }
    }
  }
} catch (error) {
  if ((error as { name?: string })?.name === 'AbortError') {
    console.log('\nStream cancelled');
  } else {
    throw error;
  }
}
```

```go title="Go" lines theme={null}
package main

import (
	"bufio"
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

func stream(ctx context.Context) error {
	body, _ := json.Marshal(map[string]any{
		"model":  "openai/gpt-4o",
		"input":  "Write a story",
		"stream": true,
	})
	req, _ := http.NewRequestWithContext(ctx, "POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("unexpected status: %s", resp.Status)
	}

	scanner := bufio.NewScanner(resp.Body)
	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
	for scanner.Scan() {
		data, ok := strings.CutPrefix(scanner.Text(), "data: ")
		if !ok || data == "[DONE]" {
			continue
		}
		var event struct {
			Type  string `json:"type"`
			Delta string `json:"delta"`
		}
		if json.Unmarshal([]byte(data), &event) == nil && event.Type == "response.output_text.delta" {
			fmt.Println(event.Delta)
		}
	}
	return scanner.Err()
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// To cancel the stream (here, after 2 seconds):
	timer := time.AfterFunc(2*time.Second, cancel)
	defer timer.Stop()

	if err := stream(ctx); err != nil {
		// Cancelling the context aborts the request, before or during the stream.
		if errors.Is(err, context.Canceled) {
			fmt.Println("Stream cancelled")
		} else {
			log.Fatal(err)
		}
	}
}

```

```bash title="cURL" lines theme={null}
# Stream a response; closing the connection (Ctrl+C, or killing curl) cancels it
trap 'echo "Stream cancelled"' INT

curl -sSfN https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Write a story",
    "stream": true
  }' |
  jq -R --unbuffered -r 'select(startswith("data: ")) | .[6:] | fromjson? | select(.type == "response.output_text.delta") | .delta'

```

```text title="Output" theme={null}
In
 the
 heart
 of
 a
 dense
,
 ancient
 forest
,
 where
 sunlight
 barely
 pierced
 through
 the
 dense
 canopy
,
 a
 young
 girl
 named
 El
ara
 lived
 in
 a
 quaint
,
 ivy
-covered
 cottage
 with
 her
 grandmother
.
 The
 villagers
 often
```

> [!WARNING]
>
> Cancellation only works for streaming requests with supported providers. For non-streaming requests or unsupported providers, the model will continue processing and you will be billed for the complete response.

### Handling errors during streaming

OpenRouter handles errors differently depending on when they occur during the streaming process:

#### Errors before the response is committed

If an error occurs before OpenRouter has committed the response, you get a standard JSON error response with the appropriate HTTP status code. That covers failures raised before the request reaches a provider, and provider failures visible at connection time such as a connection error or a non-2xx upstream status.

```json lines theme={null}
{
  "error": {
    "code": 400,
    "message": "Invalid model specified"
  }
}
```

Common HTTP status codes include:

* **400**: Bad Request (invalid parameters)
* **401**: Unauthorized (invalid API key)
* **402**: Payment Required (insufficient credits)
* **429**: Too Many Requests (rate limited)
* **502**: Bad Gateway (provider error)
* **503**: Service Unavailable (no available providers)

#### Errors after the response is committed (mid-stream)

Once the provider has returned response headers, the `200 OK` status is committed even if no token has been produced yet. Any error after that point arrives as an SSE event rather than as an HTTP status. The event shape depends on the API.

##### Responses API

The stream ends with a `response.failed` event. An abridged event looks like:

```text lines theme={null}
data: {"type":"response.failed","response":{"id":"gen-abc123", ... ,"status":"failed","output":[],"error":{"code":"server_error","message":"Provider disconnected unexpectedly"},"error_type":"provider_unavailable"},"sequence_number":12}
```

Key characteristics of mid-stream errors:

* The error is in `response.error`, and `response.status` is `"failed"`
* The canonical OpenRouter `error_type` is at the top level of `response` (see [Responses API error formats](https://openrouter.ai/docs/api_reference/errors-and-debugging.md#responses-api-apiv1responses))
* The stream schema also defines a plain `error` event (`{"type":"error","code":"...","message":"..."}`). OpenRouter reports failures with `response.failed`, but handling both is safe
* The HTTP status remains 200 OK since headers were already sent
* The stream is terminated after this event
* The error can be the first and only event in the stream, so treat a `200` carrying a `response.failed` event with no output as a failure, not a success

##### Chat Completions

The stream ends with a chunk that carries a top-level `error`:

```text lines theme={null}
data: {"id":"cmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"openai/gpt-4o","provider":"openai","error":{"code":502,"message":"Provider disconnected unexpectedly"},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"error"}]}
```

Key characteristics of mid-stream errors:

* The error appears at the **top level** alongside standard response fields (id, object, created, etc.)
* A `choices` array is included with `finish_reason: "error"` to properly terminate the stream
* The HTTP status remains 200 OK since headers were already sent
* The stream is terminated after this unified error event
* The error can be the first and only event in the stream, so treat a `200` carrying an `error` chunk with no content as a failure, not a success

See [Errors and debugging](https://openrouter.ai/docs/api_reference/errors-and-debugging.md#chat-completions-apiv1chatcompletions) for the full error formats of both APIs.

#### Code examples

Here's how to properly handle both types of errors in your streaming implementation:

```typescript title="TypeScript SDK" expandable lines theme={null}
import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

async function streamWithErrorHandling(prompt: string) {
  try {
    const stream = await openRouter.responses.send({
      responsesRequest: {
        model: 'openai/gpt-4o',
        input: prompt,
        stream: true,
      },
    });

    if (!(stream instanceof ReadableStream)) {
      throw new Error('Expected a streaming response');
    }

    for await (const event of stream) {
      // Check for mid-stream errors
      if (event.type === 'response.failed') {
        console.error(`Stream error: ${event.response.error?.message}`);
        console.log('Stream terminated due to error');
        return;
      }
      if (event.type === 'response.incomplete') {
        console.error(
          `Stream incomplete: ${event.response.incompleteDetails?.reason ?? 'unknown reason'}`,
        );
        return;
      }
      if (event.type === 'error') {
        console.error(`Stream error: ${event.message}`);
        return;
      }

      // Process normal content
      if (event.type === 'response.output_text.delta') {
        console.log(event.delta);
      }
    }
  } catch (error) {
    // Handle pre-stream errors
    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
  }
}

await streamWithErrorHandling('Write a story');

```

```python Python expandable lines theme={null}
import requests
import json

def stream_with_error_handling(prompt):
    response = requests.post(
        'https://openrouter.ai/api/v1/responses',
        headers={'Authorization': f'Bearer <OPENROUTER_API_KEY>'},
        json={
            'model': 'openai/gpt-4o',
            'input': prompt,
            'stream': True
        },
        stream=True
    )

    # Check initial HTTP status for pre-stream errors
    if response.status_code != 200:
        error_data = response.json()
        print(f"Error: {error_data['error']['message']}")
        return

    response.encoding = 'utf-8'

    # Process stream and handle mid-stream errors
    for line in response.iter_lines(decode_unicode=True):
        if line:
            line_text = line
            if line_text.startswith('data: '):
                data = line_text[6:]
                if data == '[DONE]':
                    break

                try:
                    parsed = json.loads(data)

                    # Check for mid-stream errors
                    if parsed.get('type') == 'response.failed':
                        print(f"Stream error: {parsed['response']['error']['message']}")
                        print("Stream terminated due to error")
                        break
                    if parsed.get('type') == 'response.incomplete':
                        details = parsed['response'].get('incomplete_details') or {}
                        reason = details.get('reason', 'unknown reason')
                        print(f"Stream incomplete: {reason}")
                        break
                    if parsed.get('type') == 'error':
                        print(f"Stream error: {parsed['message']}")
                        break

                    # Process normal content
                    if parsed.get('type') == 'response.output_text.delta':
                        print(parsed['delta'], end='', flush=True)

                except json.JSONDecodeError:
                    pass

stream_with_error_handling('Write a story')

```

```typescript title="TypeScript (fetch)" expandable lines theme={null}
async function streamWithErrorHandling(prompt: string) {
  const response = await fetch(
    'https://openrouter.ai/api/v1/responses',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer <OPENROUTER_API_KEY>`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'openai/gpt-4o',
        input: prompt,
        stream: true,
      }),
    }
  );

  // Check initial HTTP status for pre-stream errors
  if (!response.ok) {
    const error = await response.json();
    console.error(`Error: ${error.error.message}`);
    return;
  }

  const reader = response.body!.getReader();
  if (!reader) throw new Error('No response body');

  const decoder = new TextDecoder();
  let buffer = '';

  try {
    stream: while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      buffer += decoder.decode(value, { stream: true });

      while (true) {
        const lineEnd = buffer.indexOf('\n');
        if (lineEnd === -1) break;

        const line = buffer.slice(0, lineEnd).trim();
        buffer = buffer.slice(lineEnd + 1);

        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') break stream;

          try {
            const parsed = JSON.parse(data);

            // Check for mid-stream errors
            if (parsed.type === 'response.failed') {
              console.error(`Stream error: ${parsed.response.error?.message}`);
              console.log('Stream terminated due to error');
              return;
            }
            if (parsed.type === 'response.incomplete') {
              console.error(
                `Stream incomplete: ${parsed.response.incomplete_details?.reason ?? 'unknown reason'}`,
              );
              return;
            }
            if (parsed.type === 'error') {
              console.error(`Stream error: ${parsed.message}`);
              return;
            }

            // Process normal content
            if (parsed.type === 'response.output_text.delta') {
              console.log(parsed.delta);
            }
          } catch (e) {
            // Ignore parsing errors
          }
        }
      }
    }
  } finally {
    reader.cancel();
  }
}

await streamWithErrorHandling('Write a story');

```

```go title="Go" lines theme={null}
package main

import (
	"bufio"
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func streamWithErrorHandling(prompt string) error {
	body, _ := json.Marshal(map[string]any{
		"model":  "openai/gpt-4o",
		"input":  prompt,
		"stream": true,
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	// Handle pre-stream errors
	if resp.StatusCode != http.StatusOK {
		msg, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("%s: %s", resp.Status, msg)
	}

	scanner := bufio.NewScanner(resp.Body)
	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
	for scanner.Scan() {
		data, ok := strings.CutPrefix(scanner.Text(), "data: ")
		if !ok || data == "[DONE]" {
			continue
		}
		var event struct {
			Type     string `json:"type"`
			Delta    string `json:"delta"`
			Message  string `json:"message"`
			Response struct {
				Error *struct {
					Message string `json:"message"`
				} `json:"error"`
				IncompleteDetails *struct {
					Reason string `json:"reason"`
				} `json:"incomplete_details"`
			} `json:"response"`
		}
		if json.Unmarshal([]byte(data), &event) != nil {
			continue
		}

		// Check for mid-stream errors
		switch event.Type {
		case "response.failed":
			msg := ""
			if event.Response.Error != nil {
				msg = event.Response.Error.Message
			}
			fmt.Fprintf(os.Stderr, "Stream error: %s\n", msg)
			fmt.Println("Stream terminated due to error")
			return nil
		case "response.incomplete":
			reason := "unknown reason"
			if d := event.Response.IncompleteDetails; d != nil && d.Reason != "" {
				reason = d.Reason
			}
			fmt.Fprintf(os.Stderr, "Stream incomplete: %s\n", reason)
			return nil
		case "error":
			fmt.Fprintf(os.Stderr, "Stream error: %s\n", event.Message)
			return nil
		case "response.output_text.delta":
			// Process normal content
			fmt.Println(event.Delta)
		}
	}
	return scanner.Err()
}

func main() {
	if err := streamWithErrorHandling("Write a story"); err != nil {
		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
	}
}

```

```bash title="cURL" lines theme={null}
# Stream a response, reporting pre-stream errors (HTTP error body) and mid-stream error events
curl -sSN https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": "Write a story",
    "stream": true
  }' |
  jq -R --unbuffered -r 'sub("^data: "; "") | fromjson? |
    if .type == "response.failed" then "Stream error: \(.response.error.message)", "Stream terminated due to error"
    elif .type == "response.incomplete" then "Stream incomplete: \(.response.incomplete_details.reason // "unknown reason")"
    elif .type == "error" then "Stream error: \(.message)"
    elif .type == "response.output_text.delta" then .delta
    elif .error then "Error: \(.error.message)"
    else empty end'

```

```text title="Output" theme={null}
In
 the
 small
 town
 of
 Eld
erg
len
,
 nestled
 between
 mist
y
 mountains
 and
 dense
 forests
,
 there
 was
 a
 peculiar
 shop
 known
 only
 to
 a
 few
.
 Called
 "
Wh
im
sy
 &
 Wonders
,"
 it
 sat
 at
```

#### API-specific behavior

Different API endpoints may handle streaming errors slightly differently:

* **Responses API**: Upstream token-limit errors (such as `max_tokens_exceeded`) end the stream with a `response.incomplete` event (`incomplete_details.reason: "max_output_tokens"`) rather than an error; other failures end with `response.failed`
* **Chat Completions API**: Returns `ErrorResponse` directly if no chunks were processed, or includes error information in the response if some chunks were processed; the same token-limit errors become `finish_reason: "length"`
