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

# StreamErrorRetryProcessor

`StreamErrorRetryProcessor` 是一個**錯誤 processor**，會重試暫時性的 LLM API 及串流故障。它內置 OpenAI Responses 串流錯誤的配對功能，亦支援其他 Provider 特有錯誤格式的額外 matcher。

此 processor 在 core 中預設不會啟用。對於需要有限次數重試處理的 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 會檢查錯誤及其原因鏈中的以下項目：

- Provider 重試 metadata：`isRetryable === true`
- 內置 OpenAI Responses 串流錯誤配對
- Matcher 結果：任何已設定且傳回 `true` 的 matcher

當錯誤可重試時，processor 會傳回 `{ retry: true }`。它不會修改訊息。

設定 `delayMs` 後，processor 會先等候，然後才發出重試訊號。這對 `ECONNRESET` 等暫時性網絡錯誤很有用，因為立即重試很可能會再次失敗。延遲時間可以是固定的毫秒數，亦可以是使用錯誤 args 評估的函式（例如用來實作指數退避）。

### 重試限制

`maxRetries` 預設為 `1`，並限制此 processor 要求重試的次數。Agent 亦會透過 `maxProcessorRetries` 限制 processor 重試。當設定了錯誤 processor 而沒有設定 Agent 限制時，runtime 上限為 `10`。

如需單一重試配額，請將兩個值明確設為相同的有限值。該次呼叫的模型 `maxRetries` 應保持為 `0`，以免增加 Provider 嘗試次數。

### `Retry-After` 處理方式

對於包含 `Retry-After` response header 的可重試錯誤，processor 會透過錯誤原因鏈，以不區分大小寫的方式讀取 delta-seconds 及 HTTP-date 值。它會按照 `delayMs` 與設有上限的伺服器延遲之中較長的時間等候。

`maxRetryAfterMs` 預設為 `30_000`。它只會限制由 Provider 提供的等候時間。較長而且明確設定的 `delayMs` 會維持不變。無效或已過期的 header 會被忽略。

## 重試未知錯誤

設定 `retryUnknownErrors`，可重試不符合 Provider metadata、內置 OpenAI matcher 或自訂 matcher 的錯誤。未知錯誤重試會使用 processor 層級的 `maxRetries` 及 `delayMs` 值。已知的授權失敗（包括 HTTP `401` 及 `403` response）不會重試：

```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 policy 仍會優先於未知錯誤值。此選項預設為 `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 串流錯誤 chunk。它會重試已知的暫時性 OpenAI 錯誤碼；作為後備機制，亦會重試帶有明確重試指引（例如 `You can retry your request`）的錯誤。

`StreamErrorRetryProcessor` 預設包含此 matcher。你亦可匯入它，並在自訂重試邏輯中重用。

## Constructor 參數

**options** (`StreamErrorRetryProcessorOptions`): 重試處理的設定。

## 屬性

**id** (`'stream-error-retry-processor'`): Processor 標識符。

**name** (`'Stream Error Retry Processor'`): Processor 顯示名稱。

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): 重試串流錯誤，次數不超過設定的重試上限。

## 相關內容

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