Designing Workflows that fail gracefully

After this lesson you'll be able to configure per-step retry policies, pause a Workflow for minutes or months with sleep(), block on an external event with waitForEvent (with a safe timeout), and reason about how a Workflow instance dies for good.

A Workflow's durability comes from replaying completed steps instead of re-running them — that's the subject of the previous lesson. This lesson is about the other half: what happens when a step doesn't succeed, when the next action depends on time passing, or when the workflow needs to wait on something outside itself entirely, like a human clicking "approve." Getting this wrong doesn't crash loudly — it leaves an instance quietly stuck, sometimes forever.

How it works

Retry policies on step.do

Every step.do() call can take a retries config as its second argument. If the step's callback throws, Workflows retries it according to this policy before giving up:

let apiResult = await step.do(
  "call the payment API",
  {
    retries: {
      limit: 10,             // max attempts
      delay: "10 seconds",   // base delay between attempts
      backoff: "exponential" // "constant" | "linear" | "exponential"
    },
    timeout: "30 minutes",   // max time for a single attempt
  },
  async () => {
    const res = await fetch("https://payments.example.com/charge");
    if (!res.ok) throw new Error(`charge failed: ${res.status}`);
    return res.json();
  },
);

If you omit the config, the default is limit: 5, delay: 10 seconds, backoff: exponential, timeout: 10 minutes. Each retry attempt only re-runs that one step's callback — everything before it in the workflow is already durably recorded and is not replayed.

Sometimes a failure is known to be unrecoverable (a 400 Bad Request, a validation error) and retrying is pointless. Throw NonRetryableError to skip straight past the retry policy:

import { NonRetryableError } from "cloudflare:workflows";

await step.do("validate order", async () => {
  if (!order.customerId) {
    throw new NonRetryableError("order is missing a customerId");
  }
  // ...
});

sleep() and sleepUntil()

Workflows can pause for durations that would be absurd to hold a normal request-response connection open for — hours, days, or months — because the instance itself is suspended rather than a process sitting idle burning compute:

// relative delay
await step.sleep("cool-off period", "3 days");

// absolute point in time
await step.sleepUntil("wait until renewal", Date.parse("2026-08-01T00:00:00Z"));

Accepted units for the relative form range from seconds up to years. While a Workflow is sleeping (or blocked on a step, or waiting for an event — see below), it consumes no CPU time and costs nothing on that dimension; only active step execution is billed.

waitForEvent: pausing for something external

Retries and sleeps handle failure and time. waitForEvent handles the third case: the workflow needs input from outside itself — a webhook, a human clicking a button, another system finishing its own job — and doesn't know in advance when that will arrive.

const approval = await step.waitForEvent("wait for manager approval", {
  type: "approval-decision",
  timeout: "24 hours", // default is 24 hours if you omit this
});

type is a string (letters, digits, -, _, up to 100 chars) that a matching sendEvent call must use to reach this specific waiting step. From outside the workflow — a Worker handling a webhook, for example — you push the event in via the Workflow binding:

// in a separate Worker, e.g. a webhook handler
export default {
  async fetch(request: Request, env: Env) {
    const instance = await env.APPROVAL_WORKFLOW.get(instanceId);

    await instance.sendEvent({
      type: "approval-decision",
      payload: await request.json(),
    });

    return new Response("ok");
  },
} satisfies ExportedHandler<Env>;

Events can arrive before the workflow even reaches the waitForEvent step — Cloudflare buffers them and delivers on arrival at the matching step, so there's no race between "the webhook fires" and "the workflow gets there."

Worked example: an approval step with a timeout fallback

A purchase-order workflow that pauses mid-execution for a manager's approval, but auto-escalates instead of hanging if nobody responds within a business day:

import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from "cloudflare:workers";
import { NonRetryableError } from "cloudflare:workflows";

type Params = { orderId: string; amount: number; managerEmail: string };

export class PurchaseOrderWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const { orderId, amount, managerEmail } = event.payload;

    await step.do("validate order", async () => {
      if (amount <= 0) throw new NonRetryableError("invalid order amount");
    });

    await step.do("notify manager", { retries: { limit: 3, delay: "30 seconds", backoff: "exponential" } },
      async () => {
        await sendApprovalEmail(managerEmail, orderId, amount);
      },
    );

    let decision: { approved: boolean; by: string };
    try {
      const result = await step.waitForEvent<{ approved: boolean; by: string }>(
        "wait for manager approval",
        { type: "approval-decision", timeout: "8 hours" },
      );
      decision = result.payload;
    } catch (err) {
      // Timed out — escalate instead of leaving the instance stalled forever.
      await step.do("escalate to director", async () => {
        await sendEscalationEmail(orderId, amount);
      });
      decision = { approved: false, by: "timeout-escalation" };
    }

    if (!decision.approved) {
      await step.do("mark order rejected", async () => markRejected(orderId, decision.by));
      return;
    }

    await step.do("charge and fulfill", { retries: { limit: 5, delay: "1 minute", backoff: "exponential" } },
      async () => fulfillOrder(orderId),
    );
  }
}

The webhook that the approval email's link hits is a separate, ordinary Worker — it doesn't need to know anything about the workflow's internal state, only its instance ID and the event type string:

// src/approval-webhook.ts
export default {
  async fetch(request: Request, env: Env) {
    const { instanceId, approved, managerEmail } = await request.json();
    const instance = await env.PURCHASE_ORDER_WORKFLOW.get(instanceId);

    await instance.sendEvent({
      type: "approval-decision",
      payload: { approved, by: managerEmail },
    });

    return new Response("recorded");
  },
} satisfies ExportedHandler<Env>;

Pricing

Workflows billing has three dimensions: requests (instance creations/invocations), CPU time, and persisted state storage. As of this writing:

The detail that matters most for this lesson: time spent in step.sleep, blocked inside a retrying step.do, or parked in waitForEvent does not consume CPU time — you're billed for active execution, not wall-clock wait. An approval workflow that sits idle for eight hours costs the same in CPU time as one that gets approved in eight seconds.

Use cases

• Approval workflows. Purchase orders, content moderation, refund requests — anything where a human needs to sign off mid-process before the workflow continues, as in the worked example above.
• Scheduled multi-day sequences. Onboarding drips, trial-expiry reminders, dunning emails on failed payments — a sequence of step.sleep calls between actions, running as one durable instance instead of a cron job re-deriving state on every tick.
• Saga-pattern distributed transactions. A multi-service operation (reserve inventory, charge card, book shipment) where each step can fail independently and needs a compensating action if a later step fails — retries handle transient failures per step, and terminal failure handling drives the rollback/compensation logic.
• Waiting on async external systems. Kicking off a long-running third-party job (video transcoding, a batch export) and resuming only when that system's webhook confirms completion, rather than polling.