Retries·续

// Uses class-level defaults (10 attempts)
await this.retry(() => fetch(url));

// Overrides to 2 attempts for this specific call
await this.retry(() => fetch(url), { maxAttempts: 2 });

To disable retries for a specific task, set maxAttempts: 1:

await this.schedule(
    60,
    "oneShot",
    {},
    {
        retry: { maxAttempts: 1 },
    },
);

await this.schedule(
    60,
    "oneShot",
    {},
    {
        retry: { maxAttempts: 1 },
    },
);

RetryOptions

interface RetryOptions {
    /** Maximum number of attempts (including the first). Must be an integer >= 1. Default: 3 */
    maxAttempts?: number;
    /** Base delay in milliseconds for exponential backoff. Must be > 0 and <= maxDelayMs. Default: 100 */
    baseDelayMs?: number;
    /** Maximum delay cap in milliseconds. Must be > 0. Default: 3000 */
    maxDelayMs?: number;
}

The delay between retries uses full jitter exponential backoff:

delay = random(0, min(2^attempt * baseDelayMs, maxDelayMs))

This means early retries are fast (often under 200ms), and later retries back off to avoid overwhelming a failing service. The randomization (jitter) prevents multiple agents from retrying at the exact same moment.

How it works

Backoff strategy

The retry system uses the "Full Jitter" strategy from the AWS Architecture Blog ↗︎. Given 3 attempts with default settings:

Attempt Upper Bound Actual Delay
1 min(2^1 * 100, 3000) = 200ms random(0, 200ms)
2 min(2^2 * 100, 3000) = 400ms random(0, 400ms)
3 (no retry — final attempt) —

With maxAttempts: 5 and baseDelayMs: 500:

Attempt Upper Bound Actual Delay
1 min(2 * 500, 3000) = 1000ms random(0, 1000ms)
2 min(4 * 500, 3000) = 2000ms random(0, 2000ms)
3 min(8 * 500, 3000) = 3000ms random(0, 3000ms)
4 min(16 * 500, 3000) = 3000ms random(0, 3000ms)
5 (no retry — final attempt) —

MCP server retries

When adding an MCP server, you can configure retry options for connection and reconnection attempts:

await this.addMcpServer("github", "https://mcp.github.com", {
    retry: { maxAttempts: 5, baseDelayMs: 1000, maxDelayMs: 10000 },
});

await this.addMcpServer("github", "https://mcp.github.com", {
    retry: { maxAttempts: 5, baseDelayMs: 1000, maxDelayMs: 10000 },
});

These options are persisted and used when:

  • Restoring server connections after hibernation
  • Establishing connections after OAuth completion

Default: 3 attempts, 500ms base delay, 5s max delay.

Patterns

Retry with logging

class MyAgent extends Agent {
    async resilientTask(payload) {
        try {
            const result = await this.retry(
                async (attempt) => {
                    if (attempt > 1) {
                        console.log(`Retrying ${payload.url} (attempt ${attempt})...`);
                    }
                    const res = await fetch(payload.url);
                    if (!res.ok) throw new Error(`HTTP ${res.status}`);
                    return res.json();
                },
                { maxAttempts: 5 },
            );
            console.log("Success:", result);
        } catch (e) {
            console.error("All retries failed:", e);
        }
    }
}

class MyAgent extends Agent {
    async resilientTask(payload: { url: string }) {
        try {
            const result = await this.retry(
                async (attempt) => {
                    if (attempt > 1) {
                        console.log(`Retrying ${payload.url} (attempt ${attempt})...`);
                    }
                    const res = await fetch(payload.url);
                    if (!res.ok) throw new Error(`HTTP ${res.status}`);
                    return res.json();
                },
                { maxAttempts: 5 },
            );
            console.log("Success:", result);
        } catch (e) {
            console.error("All retries failed:", e);
        }
    }
}

Retry with fallback

class MyAgent extends Agent {
    async fetchData() {
        try {
            return await this.retry(
                () => fetch("https://primary-api.example.com/data"),
                { maxAttempts: 3, baseDelayMs: 200 },
            );
        } catch {
            // Primary failed, try fallback
            return await this.retry(
                () => fetch("https://fallback-api.example.com/data"),
                { maxAttempts: 2 },
            );
        }
    }
}

class MyAgent extends Agent {
    async fetchData() {
        try {
            return await this.retry(
                () => fetch("https://primary-api.example.com/data"),
                { maxAttempts: 3, baseDelayMs: 200 },
            );
        } catch {
            // Primary failed, try fallback
            return await this.retry(
                () => fetch("https://fallback-api.example.com/data"),
                { maxAttempts: 2 },
            );
        }
    }
}

Combining retries with scheduling

For operations that might take a long time to recover (minutes or hours), combine this.retry() for immediate retries with this.schedule() for delayed retries:

class MyAgent extends Agent {
    async syncData(payload) {
        const attempt = payload.attempt ?? 1;

try {
            // Immediate retries for transient failures (seconds)
            await this.retry(() => this.fetchAndProcess(payload.source), {
                maxAttempts: 3,
                baseDelayMs: 1000,
            });
        } catch (e) {
            if (attempt >= 5) {
                console.error("Giving up after 5 scheduled attempts");
                return;
            }

// Schedule a retry in 5 minutes for longer outages
            const delaySeconds = 300 * attempt;
            await this.schedule(delaySeconds, "syncData", {
                source: payload.source,
                attempt: attempt + 1,
            });
            console.log(`Scheduled retry ${attempt + 1} in ${delaySeconds}s`);
        }
    }
}

class MyAgent extends Agent {
    async syncData(payload: { source: string; attempt?: number }) {
        const attempt = payload.attempt ?? 1;

try {
            // Immediate retries for transient failures (seconds)
            await this.retry(() => this.fetchAndProcess(payload.source), {
                maxAttempts: 3,
                baseDelayMs: 1000,
            });
        } catch (e) {
            if (attempt >= 5) {
                console.error("Giving up after 5 scheduled attempts");
                return;
            }

// Schedule a retry in 5 minutes for longer outages
            const delaySeconds = 300 * attempt;
            await this.schedule(delaySeconds, "syncData", {
                source: payload.source,
                attempt: attempt + 1,
            });
            console.log(`Scheduled retry ${attempt + 1} in ${delaySeconds}s`);
        }
    }
}

Limitations

  • No dead-letter queue. If a queued or scheduled task fails all retry attempts, it is removed. Implement your own persistence if you need to track failed tasks.
  • Retry delays block the agent. During the backoff delay, the Durable Object is awake but idle. For short delays (under 3 seconds) this is fine. For longer recovery times, use this.schedule() instead.
  • Queue retries are head-of-line blocking. Queue items are processed sequentially. If one item is being retried with long delays, it blocks all subsequent items. If you need independent retry behavior, use this.retry() inside the callback rather than per-task retry options on queue().
  • No circuit breaker. The retry system does not track failure rates across calls. If a service is persistently down, each task will exhaust its retry budget independently.
  • shouldRetry is only available on this.retry(). The shouldRetry predicate cannot be used with schedule() or queue() because functions cannot be serialized to the database. For scheduled/queued tasks, handle non-retryable errors inside the callback itself.

Next steps

Schedule tasks

Schedule tasks for future execution.

Queue tasks

Background task queue for immediate processing.

Run Workflows

Durable multi-step processing with automatic retries.

Was this helpful?

YesNo

On this page

Retries·续 - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/agents/runtime/execution/retries/#page","headline":"Retries","description":"Retry failed operations with exponential backoff and jitter using the built-in retry system in the Agents SDK.","url":"https://developers.cloudflare.com/agents/runtime/execution/retries/","inLanguage":"en","image":"https://developers.cloudflare.com/agents/runtime/execution/retries/og.png?v=059fa67a7faaa30f","dateModified":"2026-06-03","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: Integrate Cloudflare Workflows with Agents for durable, multi-step background processing and failure recovery. title: Run Workflows image: https://developers.cloudflare.com/agents/runtime/execution/run-workflows/og.png?v=611bc41a222bbe40

Skip to content

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