Server Stream Stalled
URI: https://docs.ankatech.co/errors/server-stream-stalled
HTTP Status: 503 Service Unavailable
When you see this
A streaming operation was ended by the server because it stopped moving: no request byte was read and no response byte was written for the stall interval. The stall interval is 120 seconds by default, set in the deployment of the streaming service.
It applies to every streaming route: /api/v3/crypto/stream/*, /api/v3/migration/stream/* and the streaming /api/v3/interoperability/* routes. It measures the pause between two successive reads or writes, never the total time the transfer takes. A streaming operation has no total duration, no minimum rate and no read budget: a stream that keeps moving, however slowly, is never cut for a stall. At the instance cap, a stream that moved little in its last stall interval may instead be preempted (Server Stream Preempted). Bytes the operation's own processing moves for your request also count as progress, so a long processing phase that is still working through your data is not a stall.
The server decided to stop waiting, so the cut is never recorded as a client disconnect: the operation's audit record is one FAILURE with the code server-stream-stalled.
Common Causes
- A client that opened a streaming request and then stopped sending the body: a paused upload, a backgrounded process, a stuck producer.
- A client that stopped reading the response, or waits for the whole response before reading any of it, on an operation whose output it must drain as it is written.
- A network path that dropped silently without closing the connection, so nothing moved until the interval expired.
Response Example
{
"type": "https://docs.ankatech.co/errors/server-stream-stalled",
"title": "Service Unavailable",
"status": 503,
"detail": "A required service is temporarily unavailable. Please retry later.",
"instance": "/api/v3/crypto/stream/encrypt",
"correlationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. It carries a Content-Length, so a client can tell the complete document from a truncated body, and a Retry-After header. Quote the correlationId when contacting support.
How to Resolve
- Retry, and keep the stream moving: send the request body and read the response without pausing for as long as the stall interval.
- If a slow producer or consumer in your own pipeline is the cause, keep bytes flowing while it works.
- Set your client's streaming timeouts above the server's stall interval, so the server, not your client, decides that a stream stopped moving.
- Honour the
Retry-Afterheader before retrying.
The refusal is a problem document only before the response is committed
This 503 reaches you as a problem document only while the response is still uncommitted, that is while less than one response buffer of output has been written. Once the response is committed no status can be set: over HTTP/2 the stream is reset with an error code, and over HTTP/1.1 the body ends without its terminating chunk, so the response is visibly incomplete rather than a clean end. Operations that end with a verdict (decrypt, reencrypt, resign, decrypt-verify) also make the cut detectable by the verdict's absence. Discard any output of a stream that did not complete.
For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.