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

# StreamErrorRetryProcessor

`StreamErrorRetryProcessor` 是一種**錯誤處理器**，會重試暫時性的 LLM API 與串流失敗。它內建 OpenAI Responses 串流錯誤比對，也支援為其他 Provider 專屬錯誤結構加入比對器。

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()],
})
```

## 運作方式

處理器會檢查錯誤及其原因鏈中的下列項目：

- Provider 重試中繼資料：`isRetryable === true`
- 內建 OpenAI Responses 串流錯誤比對
- 比對器結果：任何回傳 `true` 的已設定比對器

若錯誤可以重試，處理器會回傳 `{ retry: true }`，而且不會修改訊息。

設定 `delayMs` 時，處理器會先等待，再發出重試信號。這適合用於 `ECONNRESET` 等暫時性網路錯誤，因為立即重試很可能再次失敗。延遲時間可以是固定的毫秒數，也可以是以錯誤引數計算的函式（例如用來實作指數退避）。

### 重試限制

`maxRetries` 預設為 `1`，用來限制此處理器提出的重試請求數量。Agent 也會透過 `maxProcessorRetries` 限制處理器重試。若已設定錯誤處理器，但未設定 Agent 限制，執行階段上限為 `10`。

需要單一重試預算時，請將兩個值明確設為相同的有限值。該次呼叫的模型 `maxRetries` 應維持為 `0`，以免 Provider 嘗試次數成倍增加。

### `Retry-After` 處理

對於具有 `Retry-After` 回應標頭、可以重試的錯誤，處理器會透過錯誤原因鏈，以不區分大小寫的方式讀取 delta-seconds 和 HTTP-date 值。它會比較 `delayMs` 與受限的伺服器延遲時間，並採用較長者等待。

`maxRetryAfterMs` 預設為 `30_000`，只會限制 Provider 提供的等待時間。較長的明確 `delayMs` 不受影響。無效或已過期的標頭會被忽略。

## 重試未知錯誤

設定 `retryUnknownErrors`，可重試不符合 Provider 中繼資料、內建 OpenAI 比對器或自訂比對器的錯誤。未知錯誤重試會使用處理器層級的 `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,
    }),
  ],
})
```

特定比對器的原則仍會優先於未知錯誤設定值。此選項預設為 `false`，因此除非啟用，否則不會重試未知錯誤。

## 延遲重試

搭配自訂比對器使用 `delayMs`，可以等待一段時間後再重試暫時性的網路連線重設：

```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 比對器

`isRetryableOpenAIResponsesStreamError` 會比對 `type: 'error'` 或 `type: 'response.failed'` 的 OpenAI Responses 串流錯誤區塊。它會重試已知的暫時性 OpenAI 錯誤程式碼；若未比對到，則會重試具有明確重試指引的錯誤，例如 `You can retry your request`。

`StreamErrorRetryProcessor` 預設包含此比對器。也可以匯入它，在自訂重試邏輯中重複使用。

## 建構函式參數

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

## 屬性

**id** (`'stream-error-retry-processor'`): 處理器識別碼。

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

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): 在設定的重試上限內重試串流錯誤。

## 相關資源

- [處理器介面](https://mastra.zisheng.pro/zh-TW/reference/processors/processor-interface)
- [處理器](https://mastra.zisheng.pro/zh-TW/docs/agents/processors)