Error handling

The following describes the types of errors you might encounter.

Errors establishing SSE connection

These errors can occur during server-sent events (SSE) connection establishment because of network issues. At this stage, the SSE connection is not established and the client application is notified by the onError() callback triggered by the EventSource handler. In this case, make sure to properly release previously created connection before trying to reconnect.

/* SSEHandler Java implementation example */

public void onError(Throwable t) {
  // Release  previously created connection

private void disconnect() {
  if (eventSource != null) {
  eventSource = null;

Errors while streaming

Once the SSE channel is properly established, Streams can still send errors, whether it is an internal error or some error coming from the target API. These can occur either immediately after a successful connection or after the server has sent several messages.

In this case, Streams closes the connection and no longer sends any additional event for this connection.

It is important that you explicitly close the connection on the client side to properly release allocated resources and avoid memory leaks or unnecessary server-side resource consumption.

The following is an example of SSE error event.

id: 24b01e8c-160c-4c1c-b909-3dcb72bf57ad 
event: error 
data: { 
  "status": 2005, 
  "cause": "An error occurred while streaming : HTTP/1.1 404 Not Found", 
  "message": "HTTP error. The Http response cannot be processed.", 
  "timestamp": 1558358255801, 
  "sessionId": "e53e4817-1054-4532-b606-6031922273f2" 

Line number key:

  1. Unique identifier of the SSE event
  2. SSE event type, in this case error
  3. A Json object representation of the error
  4. The error codes. See error codes for details
  5. An informative message about the error and a low-level reason
  6. A short message about what may have caused the error
  7. UTC Timestamp of the error
  8. The user’s session Id

The browser’s implementation of EventSource specification is: If the close() method is not explicitly called, for non-fatal errors the EventSource tries to reconnect, at a fixed rate, arbitrary set by the browser’s implementation (Chrome retries every 3 seconds). Refer to the specification for more details:

To handle streaming errors, your application must register to the SSE events of type error:

/* SSEHandler Java implementation */

public void onMessage(String event, MessageEvent message) throws Exception {
  if ("error".equals(event)) {
    //handle streaming errors here before trying to reconnect

Refer to the sample codes available in the different supported languages for further details.

Error codes

Error Description
2001 Source error. A generic error for any kind of error
2002 Format error. Error while parsing API’s JSON
2003 Unknown Host. The API’s host is unknown
2004 Connection Error. Error connecting to API.
2005 HTTP Error. The target API has responded in error (404, 500…​)

Related Links