Salesforce listener error management

Listeners can encounter errors due to reasons such as incorrect account configurations, exceeding transaction limits, or errors on the Salesforce system. When an error occurs, listeners are suspended abruptly.

The following are some disadvantages of not using error management:

You do not get any alerts about the errors.
The events that occur during the listener downtime are not captured and cannot be retrieved.
When information is lost, you must manually review the logs and trace the errors, which can be a time-intensive process.

For Salesforce listeners, you can manage errors by configuring an Error Callback Service Spec specification flow service. The Error Callback Service Spec flow service defines the actions that the listener must do when an unrecoverable error occurs and the listener is suspended. Few examples are submitting a ticket to the Ticketing System or sending an SMS to the operations team. These alerts help you quickly identify and address issues, minimizing the risk of data loss.

You can configure the flow service using the Select ErrorCallBackFlowService name option in the Add listener wizard. The behavior of the listener is as follows when you configure the error management option:

The listener is enabled and listening to events from Salesforce. When an error occurs:
The listener retries the action up to five times by default. If the listener succeeds, the listener continues to listen to the events. Otherwise, the configured callback flow service is started, and the runtime status of the listener is changed to suspended state. The error information is sent to the callbackService and the details can be viewed in the Status column of the Listeners page.
For instance, you can configure the callback flow service to display log messages for events that were retried and failed. A sample message is as follows.
Enable the suspended listeners after you resolve the errors manually. Or, the listener is automatically enabled after a package reload.
Note:
- For some errors, enabling the listener alone does not work. The listener and the underlying account must be disabled followed by reenablement of the listener with reenablement of the underlying account too.
- For unrecoverable errors, the listener is in a suspended state after a package reload. For example, when an organization exceeds its event limit.

The events that occurred during the listener downtime are based on the Select replay option that is provided during listener configuration. By default, the Select replay option is set to Last Received. For more information on available replay options, see step 3 in the Creating Salesforce listeners section.

The execution details for the callback Flow services that are configured for listeners can be viewed from the Monitor page and are listed under the Streaming source.

Handling errors

When a recoverable or unrecoverable error occurs, webMethods Integration moves the listener to the Suspended state. You can check the error details of a listener by either hovering over or clicking the Suspended option in the Status column.

The error handler automatically manages the recoverable errors, whereas unrecoverable errors need user intervention to bring the listener back to active status. When you hover over or click the Suspended option in the Status column, specific details about the error are displayed on the screen. You can identify the cause of the error and take the necessary actions to resolve it.

Note: During scheduled backend downtime or maintenance, it is advised that users follow the instructions that are provided by the backend system.

Table 1. List of the most common error codes, explanation of the cause, and potential resolutions.
Error code	Error message	Explanation	Action
400	API version in the URI is mandatory. URI format: '/cometd/55.0'	The API version is missing in the URI	Specify the API version at the end of the URI. For example, '/cometd/55.0'. See Creating Salesforce listeners for more information.
400	Unsupported API version. Only API versions '23.0' and above are supported. URI format: '/cometd/55.0'	The specified API version is not supported.	Specify a valid API version. Supported API versions: ‘23.0’ and above. See Creating Salesforce listeners for more information.
400	The channel that you requested to subscribe to does not exist {channel_name}	The streaming channel requested to subscribe does not exist.	Make sure that a channel is created before you subscribe.
400	Channel name not specified	The channel name is not specified.	Specify a valid channel name to subscribe to.
400	Channel subscriptions must start with a leading '/'	The specified channel name format is invalid.	Specify a valid channel name. Channel names must start with a leading slash (/).
400	Query fields {query_fields} do not exist on the topic entity	The supplied query fields do not exist on the Salesforce object that is specified in the PushTopic.	Specify valid query fields on the Salesforce object in the PushTopic.
400	The replayId {replay_id} you provided was invalid. Provide a valid ID, -2 to replay all events, or -1 to replay only new events.	The specified replay ID is invalid.	Specify a valid replay ID. Specify -2 to replay all events or -1 to replay only new events.
401	Authentication invalid	The specified authentication token or session ID is invalid.	Do the following steps to resolve this issue: Disable the suspended listener. Disable the associated connection and then re-enable it. Go back to the Listeners screen and enable the disabled listener.
401	Request requires authentication	The authentication token or session ID was not provided in the request header.	Provide a valid authentication token or session ID in the request header.
403	Cannot create channel {channel_name}	The subscription channel cannot be created, which can be due to insufficient permissions.	Make sure that the required access permissions are provided.
403	Subscriber does not have access to the entity in this topic	The subscriber does not have access to the Salesforce object in the PushTopic.	Make sure that the subscriber has access to the Salesforce object in the PushTopic.
403	Subscriber does not have access to all fields referenced in the where clause of the PushTopic.	The subscriber does not have access to all fields referenced in the WHERE clause of the PushTopic.	Make sure that the subscriber has access to all fields referenced in the WHERE clause of the PushTopic.
403	Handshake denied	The handshake request was denied.	Do the following steps to resolve this issue: Disable the suspended listener. Disable the associated connection and then re-enable it. Go back to the Listeners screen and enable the disabled listener.
403	Client has not completed handshake	The client has not completed a handshake.	Do the following steps to resolve this issue: Disable the suspended listener. Disable the associated connection and then re-enable it. Go back to the Listeners screen and enable the disabled listener.
403	Organization concurrent user limit exceeded	The maximum number of concurrent clients across all channels was exceeded.
403	Organization total events daily limit exceeded	The maximum number of delivered event notifications within a 24-hour period to all CometD clients was exceeded.	Try again after 24 hours.
403	Restricted channel	The user does not have the required permissions to subscribe to the streaming channel.	Make sure that you have the required permissions to subscribe to the streaming channel.
403	User not enabled for streaming	The user does not have the read permission on the PushTopic.	Make sure that you have the read permission on the PushTopic.
403	User not allowed to subscribe CDC without View All Data permissions	The user must have the View All Data permission to subscribe to Change Data Capture.	Make sure that you have the View All Data permission before you subscribe to Change Data Capture.
403	Unknown client	The server deleted the client CometD session due to a timeout, which can be resulting from a network failure.	This error is recoverable and the error handler automatically corrects the error. After some time, click the Refresh icon on the Listeners screen to see the updated status of the listener.
403	Subscription limit exceeded for this topic	The maximum number of concurrent clients per topic for PushTopic and generic events is exceeded.
503	Server is too busy. Please try your request again later.	The server cannot process the request because it is too busy.	This error is recoverable and the error handler automatically corrects the error. After some time, click the Refresh icon on the Listeners screen to see the updated status of the listener.
403	denied_by_security_policy: create_denied	The user that you are connecting with does not have read or create permissions for the platform event you are trying to subscribe to. This error occurs when the security policies or access settings within Salesforce restrict the creation of platform events for that user. As a result, the subscription attempt fails because it is unable to create the event on behalf of the connecting user.	To view or modify permissions that are associated with the user, do the following steps: Log in to your Salesforce account and go to the Setup link. In the Setup page, search for "Users" in the quick find search bar or select Users under the Manage Users section on the left sidebar. A list of users appears on the screen. Click the name of the specific user for whom you want to check the permissions. On the User detail page, find the Profile field and click the profile name. On the Profile detail page, scroll down to find the Platform Event Permissions section and review the permissions that are assigned to that profile for the platform event. To update the permission set, click the Edit button, select the check boxes next to the permissions, and click Save.