workflow/docs/api-reference/workflow-errors/workflow-world-error.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: WorkflowWorldError
description: Base error for failures from workflow storage backends.
type: reference
summary: Catch WorkflowWorldError to handle any error originating from a workflow world (storage backend).
related:
  - /docs/api-reference/workflow-errors/entity-conflict-error
  - /docs/api-reference/workflow-errors/run-expired-error
  - /docs/api-reference/workflow-errors/too-early-error
  - /docs/api-reference/workflow-errors/throttle-error
---

`WorkflowWorldError` is the base error class for failures originating from a workflow world (storage backend). World implementations (local, Postgres, Vercel) throw subclasses of this error when storage operations fail.

You can use `instanceof WorkflowWorldError` to catch any World-related error regardless of the specific type. The static `.is()` method only matches errors constructed directly as `WorkflowWorldError`. Use the subclass-specific `.is()` methods (for example, `EntityConflictError.is()`) to match specific error types.

<Callout>
Most world errors are handled automatically by the Workflow runtime. You will typically only encounter these errors when interacting with world storage APIs directly or when there are infrastructure-level issues.
</Callout>

```typescript lineNumbers
import { WorkflowWorldError } from "workflow/errors"
declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
declare const runId: string; // @setup
declare const event: any; // @setup

try {
  await world.events.create(runId, event);
} catch (error) {
  if (error instanceof WorkflowWorldError) { // [!code highlight]
    console.error("Storage backend error:", error.message);
  }
}
```

## API signature

### Properties

<TSDoc
definition={`
interface WorkflowWorldError {
  /** HTTP status code from the world backend, if available. */
  status?: number;
  /** Machine-readable error code, if available. */
  code?: string;
  /** The URL that was requested, if available. */
  url?: string;
  /**
   * Retry-After value in seconds, present on 429 and 425 responses, and on a
   * Vercel World 503 for a start Hook whose run is still being created.
   */
  retryAfter?: number;
  /**
   * Why the World gave \`code\`, when it says. For a start Hook request
   * refused with START_HOOK_ADMISSION_REJECTED: invalid, expired,
   * token_mismatch, ordinary_run or disabled.
   */
  reason?: string;
  /** The error message. */
  message: string;
}
export default WorkflowWorldError;`}
/>

`status`, `code` and `reason` are set where the error is thrown, in a step or outside a workflow. A `WorkflowWorldError` that reaches workflow code from a step arrives without them (`undefined`), with its name and message intact.

### Static methods

#### `WorkflowWorldError.is(value)`

Type-safe check that matches only errors constructed directly as `WorkflowWorldError`. Does not match subclasses like `EntityConflictError`. Use `instanceof` to catch all world errors, or the subclass-specific `.is()` methods.

```typescript
import { WorkflowWorldError } from "workflow/errors"
declare const error: unknown; // @setup

if (WorkflowWorldError.is(error)) {
  // error is typed as WorkflowWorldError (not subclasses)
}
```

### Subclasses

The following error types extend `WorkflowWorldError`:

- [`EntityConflictError`](/docs/api-reference/workflow-errors/entity-conflict-error): operation conflicts with entity state
- [`RunExpiredError`](/docs/api-reference/workflow-errors/run-expired-error): run has expired
- [`TooEarlyError`](/docs/api-reference/workflow-errors/too-early-error): request made before system is ready
- [`ThrottleError`](/docs/api-reference/workflow-errors/throttle-error): request was rate-limited