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 CodeError DescriptiongRPC Status Code
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.UNAVAILABLE
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.RESOURCE_EXHAUSTED
sfdc.platform.eventbus.grpc.service.unavailableThe Pub/Sub API service is unavailable. Try again later.INTERNAL
sfdc.platform.eventbus.grpc.service.auth.errorAn authentication exception occurred. Provide valid authentication via metadata headers.UNAUTHENTICATED
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.UNAUTHENTICATED
sfdc.platform.eventbus.grpc.service.auth.refresh.invalidThe auth refresh token value is invalid. Provide a valid auth refresh value.UNAUTHENTICATED
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.RESOURCE_EXHAUSTED
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.RESOURCE_EXHAUSTED
sfdc.platform.eventbus.grpc.service.tenant.licenseThe 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.PERMISSION_DENIED
Error CodeError DescriptiongRPC Status Code
sfdc.platform.eventbus.grpc.schema.meta.permissionAn error occurred while getting the schema. Possible reasons are an incorrect schema ID or incorrect credentials.PERMISSION_DENIED
sfdc.platform.eventbus.grpc.schema.api.unavailableThe schema information is unavailable.UNAVAILABLE
sfdc.platform.eventbus.grpc.schema.validation.failedSchema validation failed. The schema ID can’t be blank.INVALID_ARGUMENT
Error CodeError DescriptiongRPC Status Code
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.PERMISSION_DENIED
sfdc.platform.eventbus.grpc.topic.not.foundThe topic information for the specified topic wasn’t found. Ensure that the topic name is correct and the topic exists.NOT_FOUND
sfdc.platform.eventbus.grpc.topic.api.unavailableThe topic information is unavailable for the specified topic.UNAVAILABLE
sfdc.platform.eventbus.grpc.topic.validation.emptyAn error occurred while validating the topic information provided. The topic can’t be blank.INVALID_ARGUMENT
Error CodeError DescriptiongRPC Status Code
sfdc.platform.eventbus.grpc.publish.event.count.invalidThe request contains no events.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.publish.topic.mismatchThere’s a mismatch of topic names between requests.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.publish.auth.refresh.invalidThe refresh token shouldn’t be provided in the initial request.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.publish.topic.validation.emptyAn error occurred while validating the provided topic information. The topic can’t be blank.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.publish.stream.sweeper.timeoutNo publish request was received during the timeout period of 1,800 seconds (30 minutes). The publish stream timed out.CANCELLED

These error codes apply to both subscriptions and managed subscriptions. These errors cause the long-lived connection for the Subscribe or ManagedSubscribe RPC method to stop. Retry the RPC method call to create a new long-lived connection.

Error CodeError DescriptiongRPC Status Code
sfdc.platform.eventbus.grpc.subscription.fetch.requested.events.invalidThe requested number of events in a fetch request must be greater than zero.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.subscription.fetch.topic.mismatchThere’s a mismatch of topic names between requests.INVALID_ARGUMENT
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.INVALID_ARGUMENT
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.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.subscription.fetch.replay.repeatedDue 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.INTERNAL
sfdc.platform.eventbus.grpc.subscription.fetch.request.invalidThe fetch request is missing an auth refresh. Include an auth refresh when sending a fetch request with zero events requested. The auth refresh is for Salesforce internal use only.
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.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.subscription.internal.errorThe subscription encountered an internal error and can’t continue. Try restarting the subscription.INTERNAL
sfdc.platform.eventbus.grpc.subscription.limit.exceededThe maximum number of delivered events to all clients in the last 24 hours has been exceeded.RESOURCE_EXHAUSTED
sfdc.platform.eventbus.grpc.subscription.topic.cannot.subscribeCan’t subscribe to the specified topic. Check that you have the required permissions.PERMISSION_DENIED

These error codes apply to managed subscriptions only. These errors cause the long-lived connection for the ManagedSubscribe RPC method to stop. Retry the RPC method call to create a new long-lived connection.

Error CodeError DescriptiongRPC Status Code
sfdc.platform.eventbus.grpc.managed.subscription.already.activeAn active managed subscription with the same ID already exists. If a previous subscription with the same ID was stopped, there can be a delay before it expires. Try subscribing again later.ALREADY_EXISTS
sfdc.platform.eventbus.grpc.managed.subscription.config.deletedThe managed subscription configuration was deleted.NOT_FOUND
sfdc.platform.eventbus.grpc.managed.subscription.config.stoppedThe managed subscription configuration state is STOP. Set state to RUN before subscribing.NOT_FOUND
sfdc.platform.eventbus.grpc.managed.subscription.developer.name.not.foundThe managed subscription configuration isn't found. Ensure the developer name is correct and that the managed subscription configuration exists. If the configuration was recently created, try again.NOT_FOUND
sfdc.platform.eventbus.grpc.managed.subscription.fetch.request.events.invalidThe requested number of events in a fetch request must be greater or equal to zero.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.managed.subscription.fetch.request.invalidThe managed fetch request is missing a CommitReplayRequest or an auth refresh. Include a CommitReplayRequest or an auth refresh when sending a request with zero events requested. The auth refresh is for Salesforce internal use only.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.managed.subscription.id.or.developer.name.emptyAn error occurred while validating the managed subscription ID or developer name. Provide only one of those values.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.managed.subscription.fetch.request.commit.request.restrictedThe initial managed fetch request can’t include a CommitReplayRequest.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.managed.subscription.fetch.request.auth.request.restrictedThe initial managed fetch request can’t include an auth refresh. The auth refresh is for Salesforce internal use only.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.managed.subscription.subscription.id.invalidThe managed subscription ID is invalid. The subscription ID must be 15 or 18 characters long.INVALID_ARGUMENT
sfdc.platform.eventbus.grpc.managed.subscription.subscription.id.not.foundThe managed subscription configuration isn't found. Ensure the subscription ID is correct and that the managed subscription configuration exists. If the configuration was recently created, try again.NOT_FOUND

These errors don't cause the long-lived connection for the ManagedSubscribe RPC method to stop. These errors are part of the CommitResponse that is returned after sending a CommitReplayRequest to commit a Replay ID.

Error CodeError Description
COMMITNo Replay ID was provided to commit. Specify a Replay ID in CommitReplayRequest.
COMMITThe Replay ID provided in the commit request is invalid. Ensure the Replay ID in CommitReplayRequest is valid. If the Replay ID is old, it can be outside the event retention window and is no longer valid.
COMMITThe commit request was received before the subscription delivered any events. Wait for event delivery before attempting to commit a Replay ID.
COMMITThe Replay ID commit request failed. For information about how to handle the Replay ID commit failure, check the documentation.
COMMITThe Replay ID in this commit request is older than the currently committed Replay ID.