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).
`402` `PAYMENT_REQUIRED`	The account’s balance is zero. Appends pause; reads and tails continue.	After a top-up	Add credit on Usage & billing, and send the append again (When the balance runs out).
`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).
`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).
`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).
`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).
`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); 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.