Subscription retry policy

A subscriber might fail to process messages for several reasons. For example, the subscriber could experience temporary problems retrieving necessary data, or it might receive a message in an unexpected format.

If Pub/Sub attempts to deliver a message but the subscriber can't acknowledge it, Pub/Sub automatically tries to resend the message. This redelivery attempt is known as the subscription retry policy. This isn't a feature that you can turn on or off. However, you can choose what type of retry policy you want to use.

Before you begin

• Create a topic that you are going to use with your subscription that contains a subscription retry policy.

Required roles

To get the permissions that you need to manage topics and subscriptions, ask your administrator to grant you the Pub/Sub Editor(roles/pubsub.editor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

You can configure access control at the project level and at the individual resource level. You can create a subscription in one project and attach it to a topic located in a different project. Ensure that you have the required permissions for each project.

Types of retry policies

When you first create and configure your subscription, you can choose to use one of the following retry policies, immediate redelivery or exponential backoff. By default, subscriptions use immediate redelivery.

Note: This feature is independent from Push backoff. You can use these two features together to better control the flow of messages. In this case, the total delay is the maximum combined value of both the push backoff value and the retry policy value. If you're noticing issues with message delivery, double check how your retry policy is interacting with push backoff.

Immediate redelivery

By default, Pub/Sub tries resending the message immediately (and potentially to the same subscriber client). However, if the conditions that prevented the message acknowledgment haven't changed, immediate redelivery can cause issues. In this case, it's possible that Pub/Sub will resend multiple messages that can't be acknowledged.

To address immediate redelivery issues, Pub/Sub lets you configure an exponential backoff policy.

Exponential backoff

Exponential backoff lets you add progressively longer delays between retry attempts. After the first delivery failure, Pub/Sub waits for a minimum backoff time before retrying. For each consecutive message failure, more time is added to the delay, up to a maximum delay (0 and 600 seconds).

The maximum and minimum delay intervals are not fixed, and should be configured based on local factors to your application.

Note the following considerations about exponential backoff:

• Exponential backoff triggers on the following actions:
  • When a negative acknowledgment is received.
  • When the acknowledgment deadline of a message expires.
• Exponential backoff is only applied per-message, rather than to all the messages in a subscription (global).
• While using exponential backoff, Pub/Sub continues to deliver other messages, even if previous messages received negative acknowledgments (unless, you're using ordered message delivery).

Use the retry policy to delay the delivery and processing of a subset of messages to accommodate a transient inability to process some messages upon delivery. The feature is applied on a best-effort basis and each message is evaluated for retry policy separately.

We don't recommend to use this feature to introduce intentional delays in message delivery. If you negatively acknowledge (nack) a large number of messages on a subscription configured with a retry policy, it is possible that some of those messages are delivered with less or no backoff. Pub/Sub might also slow down the delivery of all messages if you negative acknowledgment a large number of messages.

If you need to schedule deliveries, consider using Cloud Tasks.

Configure exponential backoff

Console

When creating a new subscription, you can configure an exponential backoff retry policy using the following steps:

1. In the Google Cloud console, go to the Pub/Sub subscriptions page.

Go to subscriptions

1. Click Create subscription.

2. In the Subscription ID field, enter a name.

For information on how to name a subscription, see Guidelines to name a topic or a subscription.

1. Choose or create a topic from the drop-down menu.

The subscription receives messages from the topic.

1. Select a Delivery type.

2. Under Retry policy, select Retry after exponential backoff.

3. Enter a Minimum backoff and Maximum backoff between 0 and 600 seconds.

The default values are 10 seconds for minimum backoff, and 600 seconds for maximum backoff.

1. Click Create.

gcloud

To create a new subscription with an exponential backoff retry policy, run the following gcloud pubsub create command.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --min-retry-delay=MIN_RETRY_DELAY \
  --max-retry-delay=MAX_RETRY_DELAY

Replace the following:

• SUBSCRIPTION_ID: a unique ID for your subscription.
• TOPIC_ID: the ID of the topic that you want to attach the subscription to.
• MIN_RETRY_DELAY: the minimum backoff delay for the subscription.
• MAX_RETRY_DELAY: the maximum backoff delay for the subscription.

What's next

• Get the forwarded undeliverable messages.
• Monitor Pub/Sub applications.
• Learn message delivery concepts.