Handle Errors

If an error occurs while an RPC method executes, the Pub/Sub API throws a gRPC StatusRuntimeException that contains a status code. The exception causes the long-lived connection for the PublishStream and Subscribe RPC methods to stop. Retry the PublishStream and the Subscribe RPC methods to create a new long-lived connection.

The gRPC status codes can be found here. In your code, catch the exceptions after performing an RPC method call, and handle the error.

The status fields differ depending on the programming language. For example, in Java, the fields are code and description and in Python they're code and details. To get status fields in Java, after catching the exception, you can call the getStatus() Java method on the exception to get the Status object. Next, call getCode() and getDescription() on the status. To get status fields in Python, after catching the exception, you can call the code and details methods on the exception.

The Pub/Sub API adds a custom error code in the Trailers section of the exception. You can retrieve the custom error code by calling getTrailers() on the exception. The error code provides information about the cause of the failure.

Also, the exception contains an RPC ID that the Pub/Sub API appends to the error message after the “rpcId:" prefix. The RPC ID is also included in the Trailers section of the exception. The RPC ID identifies the method execution that caused the exception and can aid Salesforce Customer Support in troubleshooting the error. If you can’t resolve the error by looking up the error code and the documentation, contact Salesforce Customer Support for help and provide the rpcId value.

In the example gRPC exception below, the status returned is INVALID_ARGUMENT, and the custom error code from the Pub/Sub API is: [Trailer] = error-code [Value] = sfdc.platform.eventbus.grpc.subscription.fetch.replayid.corrupted

This table lists the error codes that the Pub/Sub API returns as part of the gRPC StatusRuntimeException. The gRPC status codes can be found in the gRPC documentation.

Error Code	Error Description
`io.grpc.StatusRuntimeException: UNAVAILABLE: RST_STREAM closed stream.`	An internal error occurred. Temporary network connectivity issues can cause this error. Retry the `PublishStream` or `Subscribe` RPC method.
`sfdc.platform.eventbus.grpc.concurrent.client.limit.exceeded`	The maximum number of concurrent clients across all topics has been exceeded. This limit applies to publisher and subscriber clients.
`sfdc.platform.eventbus.grpc.service.unavailable`	The Pub/Sub API service is unavailable. Try again later.
`sfdc.platform.eventbus.grpc.service.auth.error`	An authentication exception occurred. Provide valid authentication via metadata headers.
`sfdc.platform.eventbus.grpc.service.auth.headers.invalid`	The auth headers value for the specified key is invalid. Provide valid auth headers. The auth headers can’t be blank.
`sfdc.platform.eventbus.grpc.service.auth.refresh.invalid`	The auth refresh token value is invalid. Provide a valid auth refresh value.
`sfdc.platform.eventbus.grpc.service.protection.stream.limit.triggered`	The service received too many PublishRequests or FetchRequests and doesn’t have the resources to accept new requests.
`sfdc.platform.eventbus.grpc.service.protection.triggered`	The service received too many connections or requests. It doesn’t have the resources to accept new connections or requests.
`sfdc.platform.eventbus.grpc.service.tenant.license`	The Salesforce org isn’t licensed to access the Pub/Sub API. Contact Salesforce to enable the API. If you get this error even though your org is enabled for Pub/Sub API, retry the RPC method call. The cause of this error can be an intermittent issue with the service when it fails to verify the org’s access to Pub/Sub API.

Error Code	Error Description
`sfdc.platform.eventbus.grpc.schema.meta.permission`	An error occurred while getting the schema. Possible reasons are an incorrect schema ID or incorrect credentials.
`sfdc.platform.eventbus.grpc.schema.api.unavailable`	The schema information is unavailable.
`sfdc.platform.eventbus.grpc.schema.validation.failed`	Schema validation failed. The schema ID can’t be blank.

Error Code	Error Description
`sfdc.platform.eventbus.grpc.topic.meta.permission`	An error occurred while getting the metadata for the specified topic. Ensure the credentials and topic name are correct.
`sfdc.platform.eventbus.grpc.topic.not.found`	The topic information for the specified topic wasn’t found. Ensure that the topic name is correct and the topic exists.
`sfdc.platform.eventbus.grpc.topic.api.unavailable`	The topic information is unavailable for the specified topic.
`sfdc.platform.eventbus.grpc.topic.validation.empty`	An error occurred while validating the topic information provided. The topic can’t be blank.

Error Code	Error Description
`sfdc.platform.eventbus.grpc.publish.event.count.invalid`	The request contains no events.
`sfdc.platform.eventbus.grpc.publish.topic.mismatch`	There’s a mismatch of topic names between requests.
`sfdc.platform.eventbus.grpc.publish.auth.refresh.invalid`	The refresh token shouldn’t be provided in the initial request.
`sfdc.platform.eventbus.grpc.publish.topic.validation.empty`	An error occurred while validating the provided topic information. The topic can’t be blank.
`sfdc.platform.eventbus.grpc.publish.stream.sweeper.timeout`	No publish request was received during the timeout period of 120 seconds. The publish stream timed out.

Error Code	Error Description
`sfdc.platform.eventbus.grpc.subscription.fetch.requested.events.invalid`	The requested number of events in a fetch request must be greater than zero.
`sfdc.platform.eventbus.grpc.subscription.fetch.topic.mismatch`	There’s a mismatch of topic names between requests.
`sfdc.platform.eventbus.grpc.subscription.fetch.replayid.validation.failed`	The Replay ID validation failed. The `replay_preset` field in FetchRequest is set to `ReplayPreset.CUSTOM`, but no Replay ID value is set in `replay_id`. Provide a Replay ID in the `replay_id` field to subscribe after the custom Replay ID.
`sfdc.platform.eventbus.grpc.subscription.fetch.replayid.corrupted`	The Replay ID validation failed. Ensure that the `replay_id` field value in FetchRequest is valid and refers to an event that is within the retention window.
`sfdc.platform.eventbus.grpc.subscription.fetch.replay.repeated`	Due to an internal error, the server received an event that’s older than the one received earlier. Its Replay ID value is lower than that of the last received event.
`sfdc.platform.eventbus.grpc.subscription.fetch.overflow`	Too many total events were requested for this subscription. Process some events first before sending a new fetch request.
`sfdc.platform.eventbus.grpc.subscription.internal.error`	The subscription encountered an internal error and can’t continue. Try restarting the subscription.
`sfdc.platform.eventbus.grpc.subscription.limit.exceeded`	The maximum number of delivered events to all clients in the last 24 hours has been exceeded.
`sfdc.platform.eventbus.grpc.subscription.topic.cannot.subscribe`	Can’t subscribe to the specified topic. Check that you have the required permissions.