Streaming API Developer Guide

Getting Started with Streaming API
Code Examples
Client Connection Considerations
Clients and Timeouts
Clients and Cookies for Streaming API
Supported CometD Versions
HTTPS Recommended
Debugging Streaming API Applications
Handling Streaming API Errors
Streaming API Error Codes
PushTopic Events (Legacy)
Generic Events (Legacy)
Monitoring Event Usage
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Handling Streaming API Errors

Learn about some common errors and how to handle them in your streaming client.

401 Authentication Errors

Client authentication can sometimes become invalid, for example, when the OAuth token is revoked or a Salesforce admin revokes the Salesforce session. An admin 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 client authentication is not valid, the client is notified with an error. A Bayeux message is sent on the /meta/connect channel with an error value of 401::Authentication invalid and an advice field containing reconnect=none. After receiving the error notification in the channel listener, the client must reauthenticate and reconnect to receive new events.

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

Note

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

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.

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

For a code example about reauthentication, see the AuthFailureListener class in the EMPConnector GitHub project.

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.

Note

403 Unknown Client Error

If a long-lived connection is lost due to unexpected network disruption, the CometD server times out the client and deletes the client state. The CometD client attempts to reconnect but the connection is rejected with the 403::Unknown client error because the client state doesn't exist anymore. The error response returned when the client attempts to reconnect after a timeout looks similar to the following message.

When the client receives the 403::Unknown client error with the "reconnect":"handshake" advice field, the client must perform a new handshake. If the handshake is successful, the client must resubscribe to the channel in the handshake listener.

For more information, see Clients and Timeouts.

The 403::Unknown client error is sometimes returned when using more than one CometD connection. You can have only one CometD connection in one browser. If you have more than one connection because you have multiple clients or another app is using one CometD connection, your client fails to connect. In this event, ensure to turn off the other client or share the CometD connection between clients.

Note

403 Resource Limit and Validation Errors for Handshake Requests

After a client sends a handshake request, Streaming API checks the client’s API version and resource limits to ensure that the client can perform a successful connection. The following validations are performed.

  • API Version
  • Maximum concurrent clients (subscribers) across all streaming channels
  • Simultaneous connections limit on the Salesforce app servers. This limit protects against denial of service attacks.

If the client fails the validation, the response contains 403::Handshake denied in the error field, and the cause of the error is returned in the nested ext/sfdc/failureReason field. For example, the following response message is returned when the number of simultaneous connections has been exhausted.

The maximum daily event usage is checked when the client subscribes.

Note

503 Server Too Busy Error

If the Salesforce servers don’t have available resources to process your Streaming API request, a 503 error is returned in the ext/sfdc/failureReason field. This error is returned for a handshake or a connection request. For example, this response shows the 503 error on the /meta/connect channel.

If you get the 503 error, try your request after a small delay of a few minutes. This error is temporary and your request will be successful when the Salesforce app servers are available again.