ai-retry weekly downloads statistics

Retries and fallbacks for the AI SDK

Automatically handle API failures, content filtering, timeouts and other errors by switching between different AI models and providers.

ai-retry wraps a base model with a list of typed retry conditions. When a request fails with an error, or the response is not satisfying, it walks the conditions top-down to find a suitable fallback. It tracks which models have been tried and how many attempts have been made to prevent infinite loops.

Two retry shapes are supported:

• Error-based: the model throws (timeouts, rate limits, API errors). • Result-based: the model returns a successful response that still needs retrying (content filtering, schema mismatch, etc.).

Installation

[!NOTE] Version compatibility:

- Use ai-retry@0.x for AI SDK v5 - Use ai-retry@1.x for AI SDK v6 - Use ai-retry@2.x for AI SDK v7

Usage

[!NOTE] The condition API is the recommended way to configure retries. Existing code keeps working:

- The root createRetryable export and the function-style retryables (contentFilterTriggered, requestTimeout, …) are deprecated but still functional. Prefer createRetryableModel from ai-retry/-model — it is typed for that family and resolves gateway strings for it.

See the migration guide to move existing code to the condition API.

Create a retryable model with a base model and a list of conditions plus the action to take when a condition matches.

This also works with embedding models and image models, each through their own entry point:

Entry points

Pick the entry point that matches the model you pass to createRetryableModel. Each module exposes the helpers that make sense for that model family already typed for it, so no manual type annotations are needed.

| Entry point | For models passed to |

| ai-retry/language-model | generateText, generateObject, streamText, streamObject | | ai-retry/embedding-model | embed, embedMany | | ai-retry/image-model | generateImage |

Each entry point re-exports createRetryableModel plus every condition for that family. The condition helpers can also be imported from the dedicated /conditions subpath:

Vercel AI Gateway

You can pass a model as a string and it will be resolved through the default gateway provider instance from the AI SDK. Each entry point resolves strings to its own model family, so the string is typed against that family's gateway model ids.

Embedding and image entry points accept gateway strings too, resolved against their respective families:

Retries

The retries array holds the things ai-retry tries, in order, when a request fails or a result needs retrying. There are two kinds:

• Fallbacks are model instances (or gateway strings). They always match and are used as plain fallbacks. • Conditions are typed predicates produced by helpers like error() or httpStatus() and finalized with a .switch() or .retry() action. They only fire when their predicate matches.

You can think of retries as a big if-else chain — each condition is an if branch matching some error/result, and each fallback is an else branch matching anything left over. Order matters: the array is evaluated top-down until one matches.

Fallbacks

A fallback is a plain model instance (or gateway string) in retries. It always matches, so it acts as a catch-all: when no earlier condition fired, the next fallback model is tried. Each fallback is attempted once by default; use the object form to pass options like maxAttempts.

Fallbacks are tried in order. Once all of them are exhausted, a RetryError is thrown (see All retries failed).

Conditions

A Condition is a typed predicate over a retry context. The library ships two low-level builders (error() and result()) plus high-level helpers built on top of them. Every condition is finalized with one of two terminal actions, .switch() or .retry(), which turn it into a retryable.

Universal conditions

These are available from all three entry points (language-model, embedding-model, image-model).

| Helper | Kind | Matches when |

| error(predicate) | low-level | The current attempt failed and predicate(err, ctx) returns true | | error.isInstance(cls) | low-level | The error is an instance of cls (prefers cls.isInstance, else instanceof) | | error.isRetryable(flag) | low-level | APICallError.isRetryable === flag (default true) | | error.statusCode(...patterns) | low-level | Numbers match the status code exactly; regex matches the stringified code | | error.message(...patterns) | low-level | Substring (case-insensitive) or regex match against the error message | | error.isTimeout() | low-level | Error.name === 'TimeoutError' (AbortSignal.timeout() fired) | | error.isAbort() | low-level | Error.name === 'AbortError' (manual controller.abort()) | | httpStatus(...patterns) | high-level | Numbers match the status code; strings match the message; regex matches either | | timeout() | high-level | Alias for error.isTimeout() | | aborted() | high-level | Alias for error.isAbort() |

error(predicate)

Takes any predicate over the failed attempt's error. Its namespace bundles the common matchers: isInstance (matches an error class), isRetryable (defaults to true), statusCode (numbers or regex), message (case-insensitive substring or regex), and isTimeout / isAbort (match AbortSignal.timeout() firing vs a manual controller.abort()). The pattern matchers accept any number of patterns and match if any matches.

httpStatus(...patterns)

Matches an APICallError by status code (numbers), message substring (strings), or either (regex). Mix any combination in one call.

timeout()

Alias for error.isTimeout() — matches AbortSignal.timeout() firing (Error.name === 'TimeoutError'); pass a fresh timeout to the action so the fallback gets its own deadline.

aborted()

Alias for error.isAbort() — matches a manual controller.abort() (Error.name === 'AbortError').…

Description from the npm listing.