> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fault tolerance

> Make your deep agent resilient with rate limiting, retries, fallbacks, and error handling

Fault tolerance middleware keeps your deep agent running when things go wrong. Not all errors should be handled the same way: transient failures (network timeouts, rate limits) should be retried automatically, errors the LLM can recover from (bad tool output, parsing failures) should be fed back to the model, and errors that need human input should pause the agent.

## Error handling strategies

Different errors need different handling strategies:

| Error type                                                      | Who fixes it       | Strategy                                                | Middleware or feature                                                                                                                                                                                                          |
| --------------------------------------------------------------- | ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Transient errors (network issues, rate limits)                  | System (automatic) | Retry with exponential backoff                          | [ModelRetryMiddleware](https://reference.langchain.com/javascript/langchain/index/modelRetryMiddleware), [ToolRetryMiddleware](https://reference.langchain.com/javascript/langchain/index/toolRetryMiddleware)                 |
| LLM-recoverable errors (tool failures, parsing issues)          | LLM                | Convert to error `ToolMessage` and let the model adjust | @\[ToolErrorMiddleware]                                                                                                                                                                                                        |
| User-fixable errors (missing information, unclear instructions) | Human              | Pause with `interrupt()`                                | [Human-in-the-loop](/oss/javascript/deepagents/human-in-the-loop)                                                                                                                                                              |
| Provider outage                                                 | System (automatic) | Fall back to an alternative model                       | [ModelFallbackMiddleware](https://reference.langchain.com/javascript/langchain/index/modelFallbackMiddleware)                                                                                                                  |
| Excessive calls (runaway loops)                                 | System (automatic) | Cap model and tool calls per run                        | [ModelCallLimitMiddleware](https://reference.langchain.com/javascript/langchain/index/modelCallLimitMiddleware), [ToolCallLimitMiddleware](https://reference.langchain.com/javascript/langchain/index/toolCallLimitMiddleware) |
| Unexpected errors                                               | Developer          | Let them bubble up                                      | No middleware — let the exception propagate                                                                                                                                                                                    |

The sections below cover each strategy with code examples.

<Tabs>
  <Tab title="Transient errors" icon="rotate">
    Add retry middleware to automatically retry network issues and rate limits. Model calls and tool calls each have their own retry middleware with exponential backoff:

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { createAgent, modelRetryMiddleware, toolRetryMiddleware } from "langchain";

    const agent = createAgent({
      model: "google_genai:gemini-3.5-flash",
      tools: [searchTool, fetchUrlTool],
      middleware: [
        modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
        toolRetryMiddleware({
          maxRetries: 2,
          tools: ["search", "fetch_url"],
          retryOn: [TimeoutError, TypeError],
        }),
      ],
    });
    ```
  </Tab>

  <Tab title="LLM-recoverable" icon="brain">
    Use @\[ToolErrorMiddleware] to catch tool exceptions and convert them into error `ToolMessage`s so the LLM can see what went wrong and try again:

    This middleware is not yet available in the JavaScript SDK.
  </Tab>

  <Tab title="User-fixable" icon="user">
    Pause and collect information from the user when needed (like account IDs, order numbers, or clarifications). Use `interrupt_on` to pause the agent before specific tool calls:

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { createDeepAgent } from "deepagents";

    const agent = createDeepAgent({
      model: "google_genai:gemini-3.5-flash",
      tools: [sendEmailTool, deleteRecordTool],
      interruptOn: ["send_email", "delete_record"],
    });
    ```

    For the full human-in-the-loop guide, see [Human-in-the-loop](/oss/javascript/deepagents/human-in-the-loop).
  </Tab>

  <Tab title="Provider outage" icon="arrows-exchange">
    If your primary model provider goes down entirely, use [ModelFallbackMiddleware](https://reference.langchain.com/javascript/langchain/index/modelFallbackMiddleware) to switch to an alternative model:

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { createAgent, modelFallbackMiddleware } from "langchain";

    const agent = createAgent({
      model: "google_genai:gemini-3.5-flash",
      tools: [searchTool],
      middleware: [
        modelFallbackMiddleware("gpt-5.5"),
      ],
    });
    ```
  </Tab>

  <Tab title="Excessive calls" icon="gauge">
    Without limits, a confused agent can burn through your LLM API budget in minutes by looping on the same tool call or making hundreds of model calls. Set caps on both model calls and tool executions per run:

    ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { createAgent, modelCallLimitMiddleware, toolCallLimitMiddleware } from "langchain";

    const agent = createAgent({
      model: "google_genai:gemini-3.5-flash",
      tools: [searchTool],
      middleware: [
        modelCallLimitMiddleware({ runLimit: 50 }),
        toolCallLimitMiddleware({ runLimit: 200 }),
      ],
    });
    ```
  </Tab>

  <Tab title="Unexpected" icon="alert-triangle">
    Let them bubble up for debugging. Do not catch what you cannot handle. @\[ToolErrorMiddleware] only surfaces exceptions you explicitly return content for; everything else propagates unchanged:

    This pattern applies to custom middleware in the JavaScript SDK as well.
  </Tab>
</Tabs>

## Rate limiting

There are two complementary ways to limit resource usage: controlling the request rate to your model provider, and capping the total number of calls per run.

### Provider rate limiting

Chat model providers impose a limit on the number of invocations that can be made in a given time period. To control the rate at which requests are made, initialize your model with a `rate_limiter`:

### Call limits

Without limits, a confused agent can burn through your LLM API budget in minutes by looping on the same tool call or making hundreds of model calls. Set caps on both model calls and tool executions per run:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createAgent, modelCallLimitMiddleware, toolCallLimitMiddleware } from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.5-flash",
  middleware: [
    modelCallLimitMiddleware({ runLimit: 50 }),
    toolCallLimitMiddleware({ runLimit: 200 }),
  ],
});
```

Use `run_limit` to cap calls within a single invocation (resets each turn). Use `thread_limit` to cap calls across an entire conversation (requires a checkpointer). See [ModelCallLimitMiddleware](https://reference.langchain.com/javascript/langchain/index/modelCallLimitMiddleware) and [ToolCallLimitMiddleware](https://reference.langchain.com/javascript/langchain/index/toolCallLimitMiddleware) for the full configuration.

## Retries

Transient failures (network timeouts, rate limits) should be retried automatically. Model calls and tool calls each have their own retry middleware with exponential backoff:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import {
  createAgent,
  modelRetryMiddleware,
  toolRetryMiddleware,
} from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.5-flash",
  middleware: [
    // Retry model calls on rate limits, timeouts, and 5xx errors
    modelRetryMiddleware({ maxRetries: 3, backoffFactor: 2.0, initialDelayMs: 1000 }),
    // Retry specific tools that hit external APIs (not all tools)
    toolRetryMiddleware({
      maxRetries: 2,
      tools: ["search", "fetch_url"],
      retryOn: [TimeoutError, TypeError],
    }),
  ],
});
```

Scope [ToolRetryMiddleware](https://reference.langchain.com/javascript/langchain/index/toolRetryMiddleware) to specific tools rather than retrying everything. A filesystem `read_file` that fails will not benefit from a retry, but a web search that times out probably will. See [ModelRetryMiddleware](https://reference.langchain.com/javascript/langchain/index/modelRetryMiddleware) for the full configuration.

## Fallbacks

If your primary model provider goes down entirely, the fallback middleware switches to an alternative model:

```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import {
  createAgent,
  modelFallbackMiddleware,
} from "langchain";

const agent = createAgent({
  model: "google_genai:gemini-3.5-flash",
  middleware: [
    // If the primary model is fully down, fall back to an alternative
    modelFallbackMiddleware("gpt-5.5"),
  ],
});
```

See [ModelFallbackMiddleware](https://reference.langchain.com/javascript/langchain/index/modelFallbackMiddleware) for the full configuration.

## Error handling

When a tool raises an exception during execution, the agent run halts by default. Use @\[ToolErrorMiddleware] to catch specific exceptions and convert them into error ToolMessages that the model can see and recover from, instead of crashing the run.

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/fault-tolerance.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>