A Server-Sent Events endpoint answers 200 OK but with Content-Type: application/json - what does a conforming client do?

Server-Sent Events rides on an ordinary HTTP request. The client issues a GET with `Accept: text/event-stream`, and the server replies with a response body it simply never ends, writing `data:` lines and blank lines as events occur. Nothing about the exchange is special at the transport level, so the client has only the response itself to decide whether what came back is an event stream at all - and the specification makes that decision both strict and final. ## The two conditions checked before anything is dispatched A conforming client processes no events until both of these hold: - the HTTP status is `200 OK`; - the `Content-Type` response header names the media type `text/event-stream`. A `200 OK` carrying `application/json`, an HTML error page, or no `Content-Type` at all satisfies the first and fails the second. Either failure gives the same outcome, and the outcome is not "no events yet" - it is the end of that client's relationship with the endpoint. ## Failing the connection versus reestablishing it The whole rule turns on a distinction the specification draws in its own words. - **Reestablish the connection** - the client waits its current reconnection time and reissues the same request, carrying `Last-Event-ID` if it has one. This is the automatic reconnect the protocol is known for. - **Fail the connection** - the client makes no further attempt. Not after a delay, not with backoff, not later. The endpoint is finished as far as that client is concerned until the receiving application deliberately opens a new stream. | what came back | what a conforming client does | |---|---| | `200 OK` with `text/event-stream` | opens the stream and dispatches events | | `200 OK` with any other media type | fails the connection - no further attempt | | `204 No Content` | fails the connection; the defined way to say "stop" | | `301 Moved Permanently`, `307 Temporary Redirect` | follows the redirect as an ordinary HTTP request would | | `401 Unauthorized`, `403 Forbidden`, `503 Service Unavailable` | fails the connection, whatever caused the status | | connection refused, or dropped with no response | reestablishes after the reconnection time | | a good stream whose response body later ends | reestablishes after the reconnection time | Read that table once more in the direction that surprises people: a **network** failure is survivable and an **HTTP** failure is not. ## Why the symptom reads as "the client is broken" Nothing about this failure announces itself. The request completes normally - it is a finished request, not a pending one - so a live view of network traffic shows a healthy exchange. No event ever arrives, and, crucially, no second request ever arrives at the server either, so an operator watching access logs sees one request per client and then silence. Teams lose hours in the receiving application's code, which is the one place that is behaving correctly. The response the client judged is the response it actually received, which is not always the response the origin wrote. If a reverse proxy or a CDN edge substituted an error page, that page is the server's answer as far as the client is concerned, and the media type on it decides the outcome. ## Serving the endpoint so this cannot happen 1. Set `Content-Type: text/event-stream` explicitly on the streaming response rather than relying on a default. A default that produces `application/json` is the single most common cause of this failure. 2. Keep content negotiation away from a stream endpoint. An endpoint that can answer with two media types can answer with the wrong one, and one wrong answer is terminal per client. 3. Verify the response as the client sees it, through every intermediary, not as the origin wrote it. 4. Never answer a stream endpoint with an error status if you want that client back. If something is wrong and the client should return, either refuse the connection at the network level or open the stream normally and carry the condition inside an event. 5. When you genuinely want the client to stop, `204 No Content` says exactly that and the client will honour it. The design reason behind the strictness is worth stating: because a client reconnects by itself, a client that retried on every bad response would hammer a broken endpoint forever with no application code in the path to stop it. Making an unacceptable response terminal puts a hard ceiling on that loop, and hands the server one precise lever - answer correctly, or say `204 No Content` - instead of a retry storm nobody can call off.