Handle Errors

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

For details on how to retry the RPC methods, see Retry Long-Lived RPC Calls After an Error Occurs .

Inspect the Error Returned

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.

Exception Example

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

=== GRPC Exception ===
io.grpc.StatusRuntimeException: INVALID_ARGUMENT: The Replay ID validation failed. Ensure that the Replay ID is valid. rpcId: 2f6b4cee-3525-49d1-8fdb-0bd3d662062f
=== Trailers ===
[Trailer] = content-type [Value] = application/grpc
[Trailer] = rpc-id [Value] = 2f6b4cee-3525-49d1-8fdb-0bd3d662062f
[Trailer] = error-code [Value] = sfdc.platform.eventbus.grpc.subscription.fetch.replayid.corrupted
[Trailer] = type [Value] = Subscribe

Error Codes

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 Code	Error Description	gRPC 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.exceeded`	The 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.unavailable`	The Pub/Sub API service is unavailable. Try again later.	`INTERNAL`
`sfdc.platform.eventbus.grpc.service.auth.error`	An authentication exception occurred. Provide valid authentication via metadata headers.	`UNAUTHENTICATED`
`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.	`UNAUTHENTICATED`
`sfdc.platform.eventbus.grpc.service.auth.refresh.invalid`	The auth refresh token value is invalid. Provide a valid auth refresh value.	`UNAUTHENTICATED`
`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.	`RESOURCE_EXHAUSTED`
`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.	`RESOURCE_EXHAUSTED`
`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.	`PERMISSION_DENIED`

Schema Errors

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

Topic Errors

Error Code	Error Description	gRPC Status Code
`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.	`PERMISSION_DENIED`
`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.	`NOT_FOUND`
`sfdc.platform.eventbus.grpc.topic.api.unavailable`	The topic information is unavailable for the specified topic.	`UNAVAILABLE`
`sfdc.platform.eventbus.grpc.topic.validation.empty`	An error occurred while validating the topic information provided. The topic can’t be blank.	`INVALID_ARGUMENT`

Publish Errors

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

Subscription Errors

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 Code	Error Description	gRPC Status Code
`sfdc.platform.eventbus.grpc.subscription.fetch.requested.events.invalid`	The requested number of events in a fetch request must be greater than zero.	`INVALID_ARGUMENT`
`sfdc.platform.eventbus.grpc.subscription.fetch.topic.mismatch`	There’s a mismatch of topic names between requests.	`INVALID_ARGUMENT`
`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.	`INVALID_ARGUMENT`
`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.	`INVALID_ARGUMENT`
`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.	`INTERNAL`
`sfdc.platform.eventbus.grpc.subscription.fetch.request.invalid`	The 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.overflow`	Too 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.error`	The subscription encountered an internal error and can’t continue. Try restarting the subscription.	`INTERNAL`
`sfdc.platform.eventbus.grpc.subscription.limit.exceeded`	The 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.subscribe`	Can’t subscribe to the specified topic. Check that you have the required permissions.	`PERMISSION_DENIED`

Managed Subscription Errors

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 Code	Error Description	gRPC Status Code
`sfdc.platform.eventbus.grpc.managed.subscription.already.active`	An 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.deleted`	The managed subscription configuration was deleted.	`NOT_FOUND`
`sfdc.platform.eventbus.grpc.managed.subscription.config.stopped`	The managed subscription configuration state is STOP. Set state to RUN before subscribing.	`NOT_FOUND`
`sfdc.platform.eventbus.grpc.managed.subscription.developer.name.not.found`	The 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.invalid`	The 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.invalid`	The 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.empty`	An 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.restricted`	The initial managed fetch request can’t include a CommitReplayRequest.	`INVALID_ARGUMENT`
`sfdc.platform.eventbus.grpc.managed.subscription.fetch.request.auth.request.restricted`	The 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.invalid`	The 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.found`	The 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`

Errors in CommitResponse

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 Code	Error Description
`COMMIT`	No Replay ID was provided to commit. Specify a Replay ID in CommitReplayRequest.
`COMMIT`	The 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.
`COMMIT`	The commit request was received before the subscription delivered any events. Wait for event delivery before attempting to commit a Replay ID.
`COMMIT`	The Replay ID commit request failed. For information about how to handle the Replay ID commit failure, check the documentation.
`COMMIT`	The Replay ID in this commit request is older than the currently committed Replay ID.

Generate a Client Trace ID to Troubleshoot Non-Pub/Sub API Errors