Step Timeouts

Configure per-step and workflow-level timeouts to prevent runaway executions.

Overview

Timeouts prevent individual steps or entire workflows from running indefinitely. This is especially important when working with external APIs that may hang or when you need to guarantee response times.

Step Timeouts

Set a timeout for individual steps using the timeout option:

1import { relay } from "@relayplane/sdk";
2
3const result = await relay
4  .workflow("extraction")
5  .step("extract", {
6    timeout: 30000  // 30 seconds
7  })
8  .with("openai:gpt-4o")
9  .prompt("Extract data from: {{input.document}}")
10  .run({ document: "..." });

Parameters

•timeout (number) - Maximum execution time in milliseconds

If no timeout is specified, steps will wait indefinitely for the AI provider to respond. Consider setting reasonable timeouts for production workflows.

Workflow Timeouts

Set a timeout for the entire workflow in the run() options:

1const result = await relay
2  .workflow("multi-step-analysis")
3  .step("extract").with("openai:gpt-4o")
4  .step("analyze").with("anthropic:claude-sonnet-4-20250514").depends("extract")
5  .step("summarize").with("openai:gpt-4o-mini").depends("analyze")
6  .run(
7    { document: "..." },
8    { timeout: 60000 }  // 60 seconds for entire workflow
9  );

Timeout Behavior

When a timeout occurs:

1.The step or workflow is immediately cancelled
2.A TimeoutError is thrown
3.If retries are configured, the timeout counts as a retryable error
4.Subsequent steps that depend on the timed-out step are skipped

1try {
2  const result = await workflow.run(input, { timeout: 30000 });
3} catch (error) {
4  if (error.type === 'TimeoutError') {
5    console.error(`Workflow timed out after ${error.timeoutMs}ms`);
6    console.error(`Step that timed out: ${error.stepName}`);
7  }
8}

Combining Step and Workflow Timeouts

You can use both step-level and workflow-level timeouts together:

1const result = await relay
2  .workflow("robust-pipeline")
3
4  // Fast step with aggressive timeout
5  .step("quick-check", { timeout: 5000 })
6  .with("openai:gpt-4o-mini")
7  .prompt("Quick classification")
8
9  // Slower step with relaxed timeout
10  .step("deep-analysis", { timeout: 45000 })
11  .with("anthropic:claude-sonnet-4-20250514")
12  .depends("quick-check")
13  .prompt("Detailed analysis")
14
15  // Overall workflow limit
16  .run(input, { timeout: 60000 });

The workflow timeout takes precedence. If the workflow timeout is reached, all remaining steps are cancelled even if their individual timeouts haven't been reached.

Timeouts with Retries

Timeouts and retries work together. Each retry attempt gets its own timeout:

1const result = await relay
2  .workflow("resilient-extraction")
3  .step("extract", {
4    timeout: 10000,  // 10 seconds per attempt
5    retry: {
6      maxRetries: 3,
7      backoffMs: 1000
8    }
9  })
10  .with("openai:gpt-4o")
11  .prompt("Extract data")
12  .run(input);
13
14// If the step times out on first attempt:
15// - Waits 1 second (backoff)
16// - Retries with fresh 10 second timeout
17// - Repeats up to 3 times

Recommended Timeouts

Use Case	Recommended Timeout
Simple classification	5-10 seconds
Text extraction	15-30 seconds
Document analysis	30-60 seconds
Complex reasoning	60-120 seconds
Multi-step workflow	2-5 minutes total