Handling Streaming API Errors

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.

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

1{
2  "clientId": "1q1ib66fvm7kli1gfoauu95i78g", 
3  "advice": {
4    "reconnect": "none", 
5    "interval": 0
6  }, 
7  "channel": "/meta/connect", 
8  "id": 7, 
9  "error": "401::Authentication invalid", 
10  "successful": false
11}

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.

1{ 
2  "ext": { 
3    "sfdc": { 
4      "failureReason": "401::Authentication invalid" 
5    } 
6  }, 
7  "advice": { 
8    "reconnect": "none" 
9  }, 
10  "channel": "/meta/handshake", 
11  "error": "403::Handshake denied", 
12  "successful": false 
13}

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

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.

1{
2  "error":"403::Unknown client",
3  "successful":false,
4  "advice":{"interval":0,"reconnect":"handshake"}
5}

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.

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.

1{
2  "channel" : "/meta/handshake",
3  "id" : "1",
4  "error" : "403::Handshake denied",
5  "successful" : false,
6  "advice" : {
7    "reconnect" : "none"
8  },
9  "ext" : {
10    "sfdc" : {
11      "failureReason" : "403::To protect all customers from excessive use and Denial of
12         Service attacks, we limit the number of simultaneous connections per server.  
13         Your request has been denied because this limit has been exceeded.  
14         Please try your request again later."
15    },
16    "replay" : true,
17    "payload.format" : true
18  }
19}

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.

1{
2  "channel" : "/meta/connect",
3  "id" : "6",
4  "error" : "401::Authentication invalid",
5  "successful" : false,
6  "ext" : {
7    "sfdc" : {
8      "failureReason" : "503::Server is too busy.  Please try your request again later."
9    }
10  },
11  "clientId" : "b1unwa43ckd43m16v60gs6v2yv7",
12  "advice" : {
13    "reconnect" : "none",
14    "interval" : 0
15  }
16}

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.