Proposal for Handling Mid-Stream Errors in Server-Sent Events (SSE)

[brisacoder]

Current Situation

The existing AP specification defines several stream modes and standard HTTP error handling at connection initiation but lacks explicit guidance or a standardized schema for handling mid-stream errors—errors occurring after one or more SSE events have already been sent. Such errors may arise due to:

• External data source failures
• Authentication and authorization checks during streaming
• Network or infrastructure failures during data retrieval

Recommended Approach

Best practices in the SSE community generally advise the following two-step error handling mechanism:

1. Before Sending SSE Events:
   If an error is detected prior to sending any events, the server should respond immediately with the appropriate HTTP error status code (e.g., 4xx for client errors or 5xx for server errors).

2. After SSE Events Have Been Sent:
   If an error occurs mid-stream (i.e., after at least one event has been sent), the server should:

   • Send a structured SSE error event.
   • Close the SSE connection immediately afterward to signal that the stream cannot continue.

Recommended Schema for SSE Error Events

To standardize error reporting and allow consistent client-side error handling, it's beneficial to adopt a structured error event schema. A practical example is:

event: error
data: {
  "type": "authentication_error",
  "message": "Authentication failed during streaming due to expired token.",
  "code": 401,
  "timestamp": "2025-03-06T12:34:56Z"
}

A real-world schema implementation can be referenced here:

• [Human-in-Loop Error Schema Example](https://github.com/brisacoder/agent_interop/blob/82037fcfdf71ec444d507da3392a8b9581736b83/server/ap_server/routers/human_in_loop.py#L126)

This implementation clearly delineates error type, descriptive message, HTTP-like status code, and timestamp—enabling structured and actionable error handling on the client side.

References

• MDN Server-Sent Events
  https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

• HTML Standard for Server-Sent Events (W3C Living Standard)
  [https://html.spec.whatwg.org/multipage/server-sent-events.html](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events)

• Community discussions on mid-stream error handling:

  • [Stack Overflow Discussion on Mid-stream Errors in SSE](https://stackoverflow.com/questions/29971898/how-to-indicate-an-error-in-a-server-sent-events-stream)
  • [Issue discussions on GitHub regarding SSE mid-stream errors](Setting headers for EventSource whatwg/html#2177)