Batching, Retries and Delays·续

Batching, Retries and Delays·续

You can also configure a default, global delay on a per-queue basis by passing --delivery-delay-secs when creating a queue via the wrangler CLI:

# Delay all messages by 5 minutes as a default
npx wrangler queues create $QUEUE-NAME --delivery-delay-secs=300

Delay on retry

When consuming messages from a queue, you can choose to explicitly mark messages to be retried. Messages can be retried and delayed individually, or as an entire batch.

To delay an individual message within a batch:

index.jsjs

export default {
    async queue(batch, env, ctx) {
        for (const msg of batch.messages) {
            // Mark for retry and delay a singular message
            // by 3600 seconds (1 hour)
            msg.retry({ delaySeconds: 3600 });
        }
    },
};

index.tsts

export default {
    async queue(batch, env, ctx): Promise<void> {
        for (const msg of batch.messages) {
            // Mark for retry and delay a singular message
            // by 3600 seconds (1 hour)
            msg.retry({ delaySeconds: 3600 });
        }
    },
} satisfies ExportedHandler<Env>;

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def queue(self, batch):
        for msg in batch.messages:
            # Mark for retry and delay a singular message
            # by 3600 seconds (1 hour)
            msg.retry(delaySeconds=3600)

To delay a batch of messages:

index.jsjs

export default {
    async queue(batch, env, ctx) {
        // Mark for retry and delay a batch of messages
        // by 600 seconds (10 minutes)
        batch.retryAll({ delaySeconds: 600 });
    },
};

index.tsts

export default {
    async queue(batch, env, ctx): Promise<void> {
        // Mark for retry and delay a batch of messages
        // by 600 seconds (10 minutes)
        batch.retryAll({ delaySeconds: 600 });
    },
} satisfies ExportedHandler<Env>;

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def queue(self, batch):
        # Mark for retry and delay a batch of messages
        # by 600 seconds (10 minutes)
        batch.retryAll(delaySeconds=600)

You can also choose to set a default retry delay to any messages that are retried due to either implicit failure or when calling retry() explicitly. This is set at the consumer level, and is supported in both push-based (Worker) and pull-based (HTTP) consumers.

Delays can be configured via the wrangler CLI:

# Push-based consumers
# Delay any messages that are retried by 60 seconds (1 minute) by default.
npx wrangler@latest queues consumer worker add $QUEUE-NAME $WORKER_SCRIPT_NAME --retry-delay-secs=60

# Pull-based consumers
# Delay any messages that are retried by 60 seconds (1 minute) by default.
npx wrangler@latest queues consumer http add $QUEUE-NAME --retry-delay-secs=60

Delays can also be configured in the Wrangler configuration file with the delivery_delay setting for producers (when sending) and/or the retry_delay (when retrying) per-consumer:

{
    "queues": {
        "producers": [
            {
                "binding": "<BINDING_NAME>",
                "queue": "<QUEUE-NAME>",
                "delivery_delay": 60 // delay every message delivery by 1 minute
            }
        ],
        "consumers": [
            {
                "queue": "my-queue",
                "retry_delay": 300 // delay any retried message by 5 minutes before re-attempting delivery
            }
        ]
    }
}

[[queues.producers]]
binding = "<BINDING_NAME>"
queue = "<QUEUE-NAME>"
delivery_delay = 60

[[queues.consumers]]
queue = "my-queue"
retry_delay = 300

If you use both the wrangler CLI and the Wrangler configuration file to change the settings associated with a queue or a queue consumer, the most recent configuration change will take effect.

Refer to the Queues REST API documentation to learn how to configure message delays and retry delays programmatically.

Message delay precedence

Messages can be delayed by default at the queue level, or per-message (or batch).

Per-message/batch delay settings take precedence over queue-level settings.
Setting delaySeconds: 0 on a message when sending or retrying will ignore any queue-level delays and cause the message to be delivered in the next batch.
A message sent or retried with delaySeconds: <any positive integer> to a queue with a shorter default delay will still respect the message-level setting.

Apply a backoff algorithm

You can apply a backoff algorithm to increasingly delay messages based on the current number of attempts to deliver the message.

Each message delivered to a consumer includes an attempts property that tracks the number of delivery attempts made.

For example, to generate an exponential backoff ↗︎ for a message, you can create a helper function that calculates this for you:

index.jsjs

function calculateExponentialBackoff(attempts, baseDelaySeconds) {
    return baseDelaySeconds ** attempts;
}

index.tsts

function calculateExponentialBackoff(
    attempts: number,
    baseDelaySeconds: number,
): number {
    return baseDelaySeconds ** attempts;
}

def calculate_exponential_backoff(attempts, base_delay_seconds):
    return base_delay_seconds ** attempts

In your consumer, you then pass the value of msg.attempts and your desired delay factor as the argument to delaySeconds when calling retry() on an individual message:

index.jsjs

const BASE_DELAY_SECONDS = 30;

export default {
    async queue(batch, env, ctx) {
        for (const msg of batch.messages) {
            // Mark for retry with exponential backoff
            msg.retry({
                delaySeconds: calculateExponentialBackoff(
                    msg.attempts,
                    BASE_DELAY_SECONDS,
                ),
            });
        }
    },
};

index.tsts

const BASE_DELAY_SECONDS = 30;

export default {
    async queue(batch, env, ctx): Promise<void> {
        for (const msg of batch.messages) {
            // Mark for retry with exponential backoff
            msg.retry({
                delaySeconds: calculateExponentialBackoff(
                    msg.attempts,
                    BASE_DELAY_SECONDS,
                ),
            });
        }
    },
} satisfies ExportedHandler<Env>;

from workers import WorkerEntrypoint

BASE_DELAY_SECONDS = 30

class Default(WorkerEntrypoint):
    async def queue(self, batch):
        for msg in batch.messages:
            # Mark for retry and delay a singular message
            # by 3600 seconds (1 hour)
            msg.retry(
                delaySeconds=calculate_exponential_backoff(
                    msg.attempts,
                    BASE_DELAY_SECONDS,
                )
            )

Review the JavaScript API documentation for Queues.
Learn more about How Queues Works.
Understand the metrics available for your queues, including backlog and delayed message counts.

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/queues/configuration/batching-retries/#page","headline":"Batching, Retries and Delays","description":"Configure message batching, retry behavior, and delivery delays for Cloudflare Queues.","url":"https://developers.cloudflare.com/queues/configuration/batching-retries/","inLanguage":"en","image":"https://developers.cloudflare.com/queues/configuration/batching-retries/og.png?v=d8e57b6525c8c77b","dateModified":"2026-04-21","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Set up Cloudflare Queues bindings, producers, and consumers using Wrangler. title: Configure Queues image: https://developers.cloudflare.com/queues/configuration/configure-queues/og.png?v=f1d801231b835a0b

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/queues/llms.txt
Use this file to discover all available pages before exploring further.

Batching, Retries and Delays·续

Batching, Retries and Delays·续

Delay on retry

Message delay precedence

Apply a backoff algorithm

Related

On this page