Your streaming API returned 200. Then it failed
An HTTP success status starts a stream; it does not prove the operation finished. Design explicit completion, interruption and recovery semantics.
Your report endpoint sends HTTP 200, streams several rows, then loses its database connection. The client has received part of the report. It has not received a new HTTP error status, and it may have no way to tell whether more rows were expected.
At that point the server cannot replace the existing status with a different HTTP status for the same response. Consumers need another contract: how to distinguish successful completion, an explicit application failure, and an interruption with an unknown outcome.
Define completion before chunks
For a report generator, distinguish report fragments from the event confirming completion. An illustrative event vocabulary might contain report.delta, report.completed and report.failed. These are application choices, not reserved Server-Sent Events names.
Specify whether fragments are useful independently. A partial transcript may be worth displaying, while an incomplete financial export must not silently become a complete dataset. If a connection closes without the documented terminal event, represent an incomplete outcome rather than inventing success.
SSE defines framing with fields such as event, data, id and retry; it does not define business completion. The HTML standard describes framing and browser EventSource processing. A fetch-based client needs its own implementation of reconnect behavior.
Resume only with server support
An event identifier does not create a replay system. Document whether the server retains events, the retention window, ordering guarantees, and behavior when a requested position has expired.
Browser EventSource can send Last-Event-ID during reconnection according to its processing model. That requests continuity; it does not prove the application can provide it. If reconnecting starts a new generation or repeats a side effect, treat it as a new operation unless the API explicitly promises otherwise.
Duplicate handling is a separate concern. Ignoring an already processed event requires stable identity and application rules. Aborting a client connection likewise does not automatically cancel server-side work. Describe whether cancellation needs an additional request and how clients learn its outcome.
Describe items and lifecycle
OpenAPI 3.2.1 includes itemSchema for individual items in supported sequential media types. The OpenAPI SSE registry explains event modeling. Schema description does not replace delivery, retention or completion rules.
Check generator and renderer support before relying on a newer feature. In SDK documentation, show event consumption, explicit application failure and unexpected end-of-stream handling. Name the transport used: EventSource and fetch do not provide identical APIs or authentication ergonomics.
Disconnect during a test
Use a controlled server to interrupt a stream after several events, send a documented failure, return malformed data and delay long enough to exercise timeouts. Verify cleanup when a consumer stops reading. Test failures before headers as well; those remain an ordinary HTTP error path.
Measure time to first event separately from time to successful completion. A responsive first chunk can coexist with a slow or unreliable full operation. Your dashboard and SDK result type should preserve that distinction.
