Handle Invalid Connections in Streaming API

A Streaming API client is now notified with an error when the client authentication is invalidated. After receiving the error, the client can reauthenticate and reconnect to receive new events. Otherwise, the client doesn’t receive events. This change applies to all API versions.
Available in: Performance, Unlimited, Enterprise, and Developer Editions

A Streaming API client uses CometD and the Bayeux protocol to subscribe to events, including PushTopic events, generic events, and platform events. Client authentication can sometimes become invalid, for example, when the OAuth token is revoked, or a Salesforce admin invalidates the session. An administrator can revoke an OAuth token or delete a Salesforce session to prevent a client from receiving events. Sometimes a client can inadvertently invalidate its authentication by logging out from a Salesforce session.

Streaming API regularly validates the OAuth token or session ID while the client is connected. If the token or session is no longer valid, a Bayeux message is sent on the /meta/connect channel with an error value of 401::Authentication invalid. The message contains the reconnect=none value in the advice field.

Note

Note

If the OAuth or session token is not sent in the request header, the 401 error message text is 401::Request requires authentication.

Example

The error response message that is sent on the /meta/connect channel looks similar to the following.

{
  "clientId": "1q1ib66fvm7kli1gfoauu95i78g", 
  "advice": {
    "reconnect": "none", 
    "interval": 0
  }, 
  "channel": "/meta/connect", 
  "id": 7, 
  "error": "401::Authentication invalid", 
  "successful": false
}

If the client is required to perform a new handshake request due to a failed connection, the authentication error is sent on the /meta/handshake channel. The handshake request fails with a 403::Handshake denied error in the response. The 401::Authentication invalid error is nested in the ext property in the response.

Example

The error response message that is sent on the /meta/handshake channel looks similar to the following.

{ 
  "ext": { 
    "sfdc": { 
      "failureReason": "401::Authentication invalid" 
    } 
  }, 
  "advice": { 
    "reconnect": "none" 
  }, 
  "channel": "/meta/handshake", 
  "error": "403::Handshake denied", 
  "successful": false 
}
Note

Note

Invalidated client authentication doesn’t include Salesforce session expiration. The Salesforce session never expires in a CometD client. Salesforce keeps extending the timeout interval as long as the client stays connected.