> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Troubleshooting: stream requests

Last updated 29 October 2026

Look up the answer an append, a read or a snapshot request got when the stream refused it: why, whether to send it again, and what to do.

| Answer | When | Send again | What to do |
| --- | --- | --- | --- |
| `401` | The key or token is missing, expired or revoked, or the request sent a key that acts as an Agent, which answers the code `exchange_required`. | With a valid key or a new token | Send a valid key, or exchange the key for a new token, as `Authorization: Bearer`. An Agent’s key is always exchanged first (see [A short-lived token](https://tonbo.dev/docs/streams/access.md#token)). |
| `402` `PAYMENT_REQUIRED` | The account’s balance is zero. Appends pause; reads and tails continue. | After a top-up | Add credit on [Usage & billing](https://tonbo.dev/billing), and send the append again ([When the balance runs out](https://tonbo.dev/docs/databases/pricing.md#zero-balance)). |
| `403` `STREAM_LIFECYCLE` | A `PUT` or a `DELETE` at the stream’s URL. Streams are created and deleted only through the console, the CLI or the Management API. | No | `tonbo stream create` or `tonbo stream delete` (see [What a stream’s URL does not do](https://tonbo.dev/docs/streams/manage.md#lifecycle)). |
| `403` | The key is narrowed and does not reach this stream, or is read-only and the request appends. | No | Use a key that reaches the stream, or one that is not read-only (see [Narrow a key to streams](https://tonbo.dev/docs/streams/access.md#narrow)). |
| `403` with `Producer-Outcome` | The append’s producer epoch is older than one the stream has seen: a newer instance of the writer took over. | No | Stop this writer. A restarted writer moves to a higher epoch from sequence `0` ([producer write answers](https://ursula.tonbo.io/docs/specs/extensions/#53-producer-write-answers)). |
| `404` | The stream does not exist yet, is still being created, or was deleted or expired; a request with a missing or expired token may answer the same. | Once it is active | Check it with `tonbo stream show <name>`, create it first, and wait until it is `active`. |
| `404` | A snapshot read names an offset that is not the latest snapshot’s. | At the latest offset | Send `HEAD` and read the snapshot at its `Stream-Snapshot-Offset`. |
| `409` `CONTENT_TYPE_MISMATCH` | The append’s Content-Type is not the stream’s. | With the stream’s content type | Send exactly the content type `tonbo stream show` prints (see [Content types](https://tonbo.dev/docs/streams/append.md#content-types)). |
| `409` with `Stream-Closed: true` | The stream is closed, and closing is final. | No | Append to another stream; this one stays readable until it is deleted. |
| `409` `PRODUCER_SEQ_CONFLICT` | The append’s Producer-Seq skips ahead of the next one the stream expects. | With the expected number | Send the sequence number its `Producer-Expected-Seq` names. |
| `409` | Another snapshot body at the same offset, or a snapshot at an offset before the latest one. | No | Read the latest snapshot the answer names, and publish after it. |
| `410` | The offset is before the stream’s retention, which a snapshot replaced. | From the answer’s offset | Read the snapshot, or read from the answer’s `Stream-Next-Offset`, the earliest offset still readable. |
| `412` | The request carried Stream-Incarnation, and the stream was deleted and created again since. | No | Treat it as a new stream: read it from the start, with the answer’s Stream-Incarnation. |
| `413` | The body is over the request body limit. | No | Split it into several (see [Limits](https://tonbo.dev/docs/streams/limits.md)); a snapshot goes up in parts. |
| `429` | The account sent more requests per second, or held more tails open at once, than its region allows. | After Retry-After | Wait as long as `Retry-After` says, then send it again. |
| `503` | The region cannot take the request, or check an API key sent directly, for a moment. | Unchanged, after Retry-After | Wait as long as `Retry-After` says, then send the same request again; with producer headers, a repeated append applies once. |