> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# StreamErrorRetryProcessor

`StreamErrorRetryProcessor` 是一种**错误 Processor**，用于重试暂时性的 LLM API 和流故障。它内置了对 OpenAI Responses 流错误的匹配，并支持为其他 Provider 专属错误结构添加 matcher。

core 默认不启用此 Processor。对于需要有限次数重试处理的 Agent，请将其添加到 `errorProcessors`。

## 用法示例

将 `StreamErrorRetryProcessor` 添加到 `errorProcessors`：

```typescript
import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'openai-agent',
  name: 'openai-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [new StreamErrorRetryProcessor()],
})
```

## 工作原理

此 Processor 会检查错误及其 cause 链中的以下内容：

- Provider 重试元数据：`isRetryable === true`
- 内置 OpenAI Responses 流错误匹配
- Matcher 结果：任何返回 `true` 的已配置 matcher

当错误可重试时，Processor 返回 `{ retry: true }`。它不会修改消息。

设置 `delayMs` 后，Processor 会等待一段时间再发出重试信号。这适用于 `ECONNRESET` 等暂时性网络错误，因为立即重试很可能再次失败。延迟可以是固定的毫秒数，也可以是使用错误参数求值的函数（例如用于实现指数退避）。

### 重试限制

`maxRetries` 默认为 `1`，用于限制此 Processor 的重试请求次数。Agent 还会通过 `maxProcessorRetries` 限制 Processor 重试次数。如果配置了错误 Processor，但未设置 Agent 限制，则运行时上限为 `10`。

需要统一的重试预算时，请将两个值显式设置为相同的有限值。该调用的模型 `maxRetries` 应保持为 `0`，以免成倍增加 Provider 尝试次数。

### `Retry-After` 处理

对于包含 `Retry-After` 响应标头的可重试错误，Processor 会通过错误 cause 链读取不区分大小写的 delta-seconds 和 HTTP-date 值。它会等待 `delayMs` 与受限服务器延迟中较长的一段时间。

`maxRetryAfterMs` 默认为 `30_000`。它只限制 Provider 给出的等待时间。显式指定的更长 `delayMs` 不受影响。无效或已过期的标头会被忽略。

## 重试未知错误

设置 `retryUnknownErrors` 可重试不匹配 Provider 元数据、内置 OpenAI matcher 或自定义 matcher 的错误。未知错误重试使用 Processor 级的 `maxRetries` 和 `delayMs` 值。已知的授权失败不会重试，包括 HTTP `401` 和 `403` 响应：

```typescript
import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'resilient-agent',
  name: 'Resilient agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [
    new StreamErrorRetryProcessor({
      retryUnknownErrors: true,
      maxRetries: 2,
      delayMs: 3000,
    }),
  ],
})
```

特定 matcher 策略的优先级仍高于未知错误的值。此选项默认为 `false`，因此除非启用它，否则不会重试未知错误。

## 延迟重试

将 `delayMs` 与自定义 matcher 配合使用，可等待后重试暂时性的网络重置：

```typescript
import { Agent } from '@mastra/core/agent'
import { StreamErrorRetryProcessor } from '@mastra/core/processors'

const isECONNRESET = (error: unknown) => {
  if (!error || typeof error !== 'object') return false
  const code = (error as { code?: unknown }).code
  if (typeof code === 'string' && code.toUpperCase() === 'ECONNRESET') return true
  const message = error instanceof Error ? error.message : undefined
  return typeof message === 'string' && /econnreset|socket hang up/i.test(message)
}

export const agent = new Agent({
  id: 'resilient-agent',
  name: 'resilient-agent',
  instructions: 'You are a helpful assistant.',
  model: 'openai/gpt-5',
  errorProcessors: [
    new StreamErrorRetryProcessor({
      maxRetries: 2,
      delayMs: ({ retryCount }) => Math.min(1000 * 2 ** retryCount, 30000),
      matchers: [isECONNRESET],
    }),
  ],
})
```

## 默认 OpenAI Responses matcher

`isRetryableOpenAIResponsesStreamError` 匹配 `type: 'error'` 或 `type: 'response.failed'` 的 OpenAI Responses 流错误块。它会重试已知的暂时性 OpenAI 错误代码；作为后备，还会重试带有 `You can retry your request` 等明确重试指引的错误。

`StreamErrorRetryProcessor` 默认包含此 matcher。你也可以导入它，并在自定义重试逻辑中重用。

## 构造函数参数

**options** (`StreamErrorRetryProcessorOptions`): 重试处理的配置。

## 属性

**id** (`'stream-error-retry-processor'`): Processor 标识符。

**name** (`'Stream Error Retry Processor'`): Processor 显示名称。

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): 重试流错误，次数不超过配置的重试限制。

## 相关内容

- [Processor 接口](https://mastra.zisheng.pro/reference/processors/processor-interface)
- [Processors](https://mastra.zisheng.pro/docs/agents/processors)