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

Workflow SDK - Build durable, resilient, and observable workflows

---
title: ThrottleError
description: Thrown when a request is rate-limited by the workflow backend.
type: reference
summary: Catch ThrottleError when a workflow storage operation is rate-limited (HTTP 429).
related:
  - /docs/api-reference/workflow-errors/workflow-world-error
  - /docs/api-reference/workflow-errors/too-early-error
---

`ThrottleError` is thrown when a request to the workflow backend is rate-limited. It corresponds to HTTP 429 Too Many Requests semantics.

The `retryAfter` property contains the number of seconds to wait before retrying.

<Callout>
The Workflow runtime handles this error automatically by backing off and retrying. You will only encounter it when interacting with world storage APIs directly.
</Callout>

```typescript lineNumbers
import { ThrottleError } 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 (ThrottleError.is(error)) { // [!code highlight]
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  }
}
```

## API Signature

### Properties

<TSDoc
definition={`
interface ThrottleError {
  /** The number of seconds to wait before retrying. Present when the server sends a Retry-After header. */
  retryAfter?: number;
  /** The error message. */
  message: string;
}
export default ThrottleError;`}
/>

### Static Methods

#### `ThrottleError.is(value)`

Type-safe check for `ThrottleError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.

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

if (ThrottleError.is(error)) {
  // error is typed as ThrottleError
}
```