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 gRPC status codes can be found here. In your code, catch the exceptions after performing an RPC method call, and handle the error. After catching the exception, you can call the getStatus() method on the exception to get the Status.

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.

General Errors

Error CodeError Description
sfdc.platform.eventbus.grpc.concurrent.client.limit.exceededThe maximum number of concurrent clients across all topics has been exceeded. This limit applies to publisher and subscriber clients.
sfdc.platform.eventbus.grpc.service.unavailableThe Pub/Sub API service is unavailable.
sfdc.platform.eventbus.grpc.service.auth.errorAn authentication exception occurred. Provide valid authentication via metadata headers.
sfdc.platform.eventbus.grpc.service.auth.headers.invalidThe 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.invalidThe auth refresh token value is invalid. Provide a valid auth refresh value.
sfdc.platform.eventbus.grpc.service.protection.stream.limit.triggeredThe service received too many PublishRequests or FetchRequests and doesn’t have the resources to accept new requests.
sfdc.platform.eventbus.grpc.service.protection.triggeredThe 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.licenseThe Salesforce org is not 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.

Schema Errors

Error CodeError Description
sfdc.platform.eventbus.grpc.schema.meta.permissionAn error occurred while getting the schema. Possible reasons are an incorrect schema ID or incorrect credentials.
sfdc.platform.eventbus.grpc.schema.api.unavailableThe schema information is unavailable.
sfdc.platform.eventbus.grpc.schema.validation.failedSchema validation failed. The schema ID can't be blank.

Topic Errors

Error CodeError Description
sfdc.platform.eventbus.grpc.topic.meta.permissionAn error occurred while getting the metadata for the specified topic. Ensure the credentials and topic name are correct.
sfdc.platform.eventbus.grpc.topic.not.foundThe topic information for the specified topic was not found. Ensure the topic name is correct and that the topic exists.
sfdc.platform.eventbus.grpc.topic.api.unavailableThe topic information is unavailable for the specified topic.
sfdc.platform.eventbus.grpc.topic.validation.emptyAn error occurred while validating the topic information provided. The topic can’t be blank.

Publish Errors

Error CodeError Description
sfdc.platform.eventbus.grpc.publish.event.count.invalidThe request contains no events.
sfdc.platform.eventbus.grpc.publish.topic.mismatchThere is a mismatch of topic names between requests.
sfdc.platform.eventbus.grpc.publish.auth.refresh.invalidThe refresh token shouldn’t be provided in the initial request.
sfdc.platform.eventbus.grpc.publish.topic.validation.emptyAn error occurred while validating the provided topic information. The topic can’t be blank.
sfdc.platform.eventbus.grpc.publish.stream.sweeper.timeoutNo publish request was received during the timeout period of 120 seconds. The publish stream timed out.

Subscription Errors

Error CodeError Description
sfdc.platform.eventbus.grpc.subscription.fetch.requested.events.invalidThe requested number of events in a fetch request must be greater than zero.
sfdc.platform.eventbus.grpc.subscription.fetch.topic.mismatchThere is a mismatch of topic names between requests.
sfdc.platform.eventbus.grpc.subscription.fetch.replayid.validation.failedThe 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.corruptedThe 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.repeatedDue to an internal error, the server received an event that is 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.overflowToo many total events were requested for this subscription. Process some events first before sending a new fetch request.
sfdc.platform.eventbus.grpc.subscription.internal.errorThe subscription encountered an internal error and can’t continue. Try restarting the subscription.
sfdc.platform.eventbus.grpc.subscription.limit.exceededThe maximum number of delivered events to all clients in the last 24 hours has been exceeded.
sfdc.platform.eventbus.grpc.subscription.topic.cannot.subscribeCan’t subscribe to the specified topic. Check that you have the required permissions.