API Referenceworkflow/errors

WorkflowWorldError

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.

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.

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) {
    console.error("Storage backend error:", error.message);
  }
}

API signature

Properties

NameTypeDescription
statusnumberHTTP status code from the world backend, if available.
codestringMachine-readable error code, if available.
urlstringThe URL that was requested, if available.
retryAfternumberRetry-After value in seconds, present on 429 and 425 responses.
messagestringThe error message.

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.

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:

PreviousWorkflowRuntimeErrorNextThrottleError