Skip to content

Server Stream Preempted

URI: https://docs.ankatech.co/errors/server-stream-preempted
HTTP Status: 503 Service Unavailable

When you see this

Under capacity pressure, a stream that moved less than 64 KiB in the last stall window may be ended with server-stream-preempted so a new stream can start.

Each streaming instance admits a bounded number of streams at once. When a new streaming request arrives that the instance's streaming cap would refuse, the instance may end one existing stream that is barely moving instead of refusing the newcomer:

  • only a stream at least one stall interval old (120 seconds by default) is considered;
  • only a stream that moved fewer than 65,536 bytes over the last stall interval;
  • among those, the one with the least progress, the oldest on a tie, and at most one per arriving request.

A stream on an instance with a free slot is never preempted, whatever its progress, and a stream that keeps moving at least 64 KiB per stall interval is never preempted. A request refused by a per-tenant bound never preempts another stream. The operation's audit record is one FAILURE with the code server-stream-preempted.

The arriving request waits at most 2 seconds for the slot the preempted stream frees, and is admitted with it. If the slot does not come within that time, or if four requests are already waiting for one, or if no stream qualifies, the arriving request is refused as any request beyond the cap is: 429 streaming-concurrency-limit with Retry-After: 5.

Common Causes

  • A stream that has moved almost nothing for a long time, on a streaming instance that is full when another request arrives: a client trickling its upload, or reading its response very slowly.
  • A client that keeps a stream open while it waits on something else.

Response Example

{
  "type": "https://docs.ankatech.co/errors/server-stream-preempted",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "A required service is temporarily unavailable. Please retry later.",
  "instance": "/api/v3/crypto/stream/decrypt",
  "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 Retry-After: 30. The response names no other tenant and no other request. Quote the correlationId when contacting support.

How to Resolve

  1. Retry after the Retry-After delay.
  2. Keep the stream moving: send the request body and read the response as fast as your pipeline allows. A stream that moves at least 64 KiB per stall interval is never preempted.

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. 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.