[Workflows] Add delay function docs (#31850)

* [Workflows] Add delay function docs

* Apply suggestions from code review

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>
Co-authored-by: Nuno Pereira <nunoafonso2002@gmail.com>

* Rename 2026-07-02-dynamic-retry-delays.mdx to 2026-07-03-dynamic-retry-delays.mdx

* [Workflows] Update publish date

---------

Co-authored-by: ask-bonk[bot] <249159057+ask-bonk[bot]@users.noreply.github.com>
Co-authored-by: Nuno Pereira <nunoafonso2002@gmail.com>

Author: 3 people

src/content/changelog/workflows/2026-07-09-dynamic-retry-delays.mdx

@@ -0,0 +1,42 @@
+---
+title: Workflows now supports delay functions when retrying
+description: Workflows step retries now support delay functions, so you can change the next retry delay based on the failed attempt and error.
+products:
+  - workflows
+date: 2026-07-09 12:00:00 UTC
+---
+
+import { TypeScriptExample } from "~/components";
+
+With [Workflows](/workflows/), you can configure built-in retry behavior for each step. Previously, you could configure step retries with fixed delay durations, such as seconds, minutes, or hours, and backoff strategies such as `constant`, `linear`, or `exponential`.
+
+Step retries now support dynamic delay functions. Instead of choosing only a base delay and backoff strategy, pass a function to `retries.delay` and calculate the next delay from the failed attempt and thrown error.
+
+This is useful when retries should depend on the failure. Your Workflow may need to wait longer after a rate-limit error, but retry sooner after a short network failure. The delay function can also accommodate provider guidance if, for example, a downstream API returns a `Retry-After` value in its error messaging.
+
+<TypeScriptExample>
+
+```ts
+await step.do(
+	"sync customer",
+	{
+		retries: {
+			limit: 5,
+			delay: ({ ctx, error }) => {
+				if (error.message.includes("rate limit")) {
+					return `${ctx.attempt * 30} seconds`;
+				}
+
+				return "10 seconds";
+			},
+		},
+	},
+	async () => {
+		await syncCustomer();
+	},
+);
+```
+
+</TypeScriptExample>
+
+Dynamic delay functions can return a duration string, a number, or a promise that resolves to a duration. Use them to add adaptive retry behavior without writing separate queue or scheduling logic. For more information, refer to [Sleeping and retrying](/workflows/build/sleeping-and-retrying/).

src/content/docs/workflows/build/sleeping-and-retrying.mdx

@@ -74,7 +74,7 @@ const defaultConfig: WorkflowStepConfig = {
 When providing your own `StepConfig`, you can configure:
 
 - The total number of attempts to make for a step (limited to 10,000 retries per step)
-- The delay between attempts (accepts both `number` (ms) or a human-readable format)
+- The delay between attempts. Use a fixed duration as a `number` in milliseconds or a human-readable string, or use a function that returns the next delay.
 - What backoff algorithm to apply between each attempt: any of `constant`, `linear`, or `exponential`
 - When to timeout (in duration) before considering the step as failed (including during a retry attempt, as the timeout is set per attempt)
 
@@ -97,6 +97,42 @@ let someState = await step.do(
 );
 ```
 
+### Set a dynamic retry delay
+
+Use a delay function when the next retry delay should depend on the failed attempt or the thrown error. This gives you more control than a fixed delay with `constant`, `linear`, or `exponential` backoff. It is useful for rate limits, downstream provider recovery, and short network failures.
+
+The delay function receives an object with:
+
+- `ctx` - the current [`WorkflowStepContext`](/workflows/build/step-context/), including `ctx.attempt`.
+- `error` - the error that caused the retry.
+
+Return a duration string, a number in milliseconds, or a promise that resolves to either value.
+
+<TypeScriptExample>
+
+```ts
+await step.do(
+	"sync customer",
+	{
+		retries: {
+			limit: 5,
+			delay: ({ ctx, error }) => {
+				if (error.message.includes("rate limit")) {
+					return `${ctx.attempt * 30} seconds`;
+				}
+
+				return "10 seconds";
+			},
+		},
+	},
+	async () => {
+		await syncCustomer();
+	},
+);
+```
+
+</TypeScriptExample>
+
 ## Force a Workflow instance to fail
 
 You can also force a Workflow instance to fail and _not_ retry by throwing a `NonRetryableError` from within the step.

src/content/docs/workflows/build/step-context.mdx

@@ -32,6 +32,8 @@ type WorkflowStepContext = {
 | `attempt`    | `number`                                                                 | The current attempt number (1-indexed). `1` on the first try, `2` on the first retry, and so on.                                                |
 | `config`     | [`WorkflowStepConfig`](/workflows/build/workers-api/#workflowstepconfig) | The resolved retry and timeout configuration for this step, including any defaults applied by the runtime.                                      |
 
+If a step config's `retries.delay` is a function, the dynamic delay is not exposed on `ctx.config.retries.delay`. The delay function receives its own context object with the current step context and the error that caused the retry.
+
 ## Access the context
 
 Pass a parameter to your `step.do` callback to receive the context object:
@@ -65,6 +67,8 @@ await step.do(
 );
 ```
 
+To configure delay functions, refer to [Set a dynamic retry delay](/workflows/build/sleeping-and-retrying/#set-a-dynamic-retry-delay).
+
 ## Examples
 
 ### Adjust behavior based on retry attempt

src/content/docs/workflows/build/workers-api.mdx

@@ -197,17 +197,27 @@ Review the documentation on [events and parameters](/workflows/build/events-and-
 ## WorkflowStepConfig
 
 ```ts
+export type WorkflowDynamicDelayContext = {
+	ctx: WorkflowStepContext;
+	error: Error;
+};
+
+export type WorkflowDelayFunction = (
+	input: WorkflowDynamicDelayContext,
+) => string | number | Promise<string | number>;
+
 export type WorkflowStepConfig = {
 	retries?: {
 		limit: number;
-		delay: string | number;
+		delay: string | number | WorkflowDelayFunction;
 		backoff?: WorkflowBackoff;
 	};
 	timeout?: string | number;
 };
 ```
 
 - A `WorkflowStepConfig` is an optional argument to the `do` method of a `WorkflowStep` and defines properties that allow you to configure the retry behaviour of that step.
+- Set `retries.delay` to a fixed duration, or pass a `WorkflowDelayFunction` to calculate the next retry delay from the current step context and thrown error.
 
 Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how Workflows are retried.