Error Reference

This reference documents all error types in Workflow DevKit, covering both workflow-level errors and runtime errors. Understanding these errors helps you build robust, production-ready workflows.

Error Categories

Workflow DevKit errors fall into two main categories:

Workflow Errors

Errors you can throw and handle within your workflow code to control execution flow:

FatalError - Stop retries and fail the step immediately
RetryableError - Customize retry timing and behavior

Runtime Errors

Errors thrown by the Workflow DevKit when internal operations fail:

WorkflowError - Base class for all Workflow DevKit errors
WorkflowAPIError - HTTP request failures
WorkflowRunFailedError - Workflow execution failures
WorkflowRunNotCompletedError - Accessing incomplete run results
WorkflowRuntimeError - Internal runtime issues
WorkflowRunNotFoundError - Missing workflow runs
WorkflowRunCancelledError - Cancelled workflow runs
RunNotSupportedError - Version incompatibility

Quick Start

Handling API Errors

import { WorkflowAPIError } from 'workflow';

try {
  await startWorkflow('myWorkflow', input);
} catch (error) {
  if (error instanceof WorkflowAPIError) {
    console.error(`API error (${error.status}):`, error.message);
    if (error.retryAfter) {
      console.log(`Retry after ${error.retryAfter} seconds`);
    }
  }
}

Using FatalError in Steps

import { FatalError } from 'workflow';

async function validateUser(userId: string) {
  "use step";
  
  const user = await fetchUser(userId);
  
  if (!user) {
    // Don't retry - user doesn't exist
    throw new FatalError('User not found');
  }
  
  return user;
}

Customizing Retry Timing

import { RetryableError } from 'workflow';

async function callRateLimitedAPI(endpoint: string) {
  "use step";
  
  const response = await fetch(endpoint);
  
  if (response.status === 429) {
    // Retry after 1 minute
    throw new RetryableError('Rate limited', {
      retryAfter: '1m'
    });
  }
  
  return response.json();
}

Error Documentation Pages

Workflow Errors

FatalError

Thrown to indicate an unrecoverable error that should not be retried. Use this when a step encounters a permanent failure condition like invalid input or missing resources.When to use:

Resource not found (404)
Invalid input validation
Permission denied (403)
Business logic violations

RetryableError

Thrown to customize retry behavior with specific timing. Use this when you know how long to wait before retrying (e.g., rate limits, backpressure).When to use:

Rate limiting (429)
Temporary service unavailability
Exponential backoff scenarios
Custom retry delays

Runtime Errors

Common Error Patterns

Catching Specific Error Types

import { 
  WorkflowAPIError, 
  WorkflowRunFailedError,
  WorkflowRunNotFoundError 
} from 'workflow';

try {
  const run = await getRun(runId);
  const result = await run.result;
} catch (error) {
  if (WorkflowRunNotFoundError.is(error)) {
    console.error('Run does not exist:', error.runId);
  } else if (WorkflowRunFailedError.is(error)) {
    console.error('Run failed:', error.cause.message);
  } else if (WorkflowAPIError.is(error)) {
    console.error('API error:', error.status, error.message);
  }
}

Handling Rate Limits

import { RetryableError, WorkflowAPIError } from 'workflow';

async function callAPI(endpoint: string) {
  "use step";
  
  try {
    const response = await fetch(endpoint);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      throw new RetryableError('Rate limited', {
        retryAfter: retryAfter ? `${retryAfter}s` : '60s'
      });
    }
    
    return response.json();
  } catch (error) {
    if (WorkflowAPIError.is(error) && error.retryAfter) {
      throw new RetryableError('API rate limited', {
        retryAfter: error.retryAfter * 1000 // Convert seconds to ms
      });
    }
    throw error;
  }
}

Exponential Backoff

import { RetryableError, getStepMetadata } from 'workflow';

async function unreliableOperation() {
  "use step";
  
  const metadata = getStepMetadata();
  
  try {
    return await performOperation();
  } catch (error) {
    // Exponential backoff: 1s, 4s, 16s, 64s...
    const delayMs = (metadata.attempt ** 2) * 1000;
    throw new RetryableError('Operation failed, retrying...', {
      retryAfter: delayMs
    });
  }
}

unreliableOperation.maxRetries = 5;

Best Practices

Use FatalError for permanent failures - Don’t waste retries on errors that won’t succeed
Use RetryableError for known delays - Respect rate limits and backpressure signals
Check error types with .is() methods - Type-safe error checking works across contexts
Set appropriate maxRetries - Default is 3, adjust based on your use case
Make retry logic idempotent - Steps may execute multiple times
Include context in error messages - Help debugging by providing relevant details

Getting Started

Installation

Core Concepts

Building AI Agents

How It Works

Deployment

Observability

Testing

Error Reference

Error Categories

Workflow Errors

Runtime Errors

Quick Start

Handling API Errors

Using FatalError in Steps

Customizing Retry Timing

Error Documentation Pages

FatalError

RetryableError

WorkflowError

WorkflowAPIError

WorkflowRunFailedError

WorkflowRunNotCompletedError

WorkflowRuntimeError

WorkflowRunNotFoundError

WorkflowRunCancelledError

RunNotSupportedError

Common Error Patterns

Catching Specific Error Types

Handling Rate Limits

Exponential Backoff

Best Practices

​Error Categories

​Workflow Errors

​Runtime Errors

​Quick Start

​Handling API Errors

​Using FatalError in Steps

​Customizing Retry Timing

​Error Documentation Pages

​Common Error Patterns

​Catching Specific Error Types

​Handling Rate Limits

​Exponential Backoff

​Best Practices

​Related Resources

Error Categories

Workflow Errors

Runtime Errors

Quick Start

Handling API Errors

Using FatalError in Steps

Customizing Retry Timing

Error Documentation Pages

Common Error Patterns

Catching Specific Error Types

Handling Rate Limits

Exponential Backoff

Best Practices

Related Resources