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

# StreamErrorRetryProcessor

`StreamErrorRetryProcessor` は、一時的な LLM API エラーとストリーム障害を再試行する **error processor** です。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 は、エラーとその cause chain について次の項目を確認します。

- provider の再試行メタデータ: `isRetryable === true`
- 組み込みの OpenAI Responses ストリームエラーとの一致
- matcher の結果: 設定した matcher のいずれかが `true` を返す

エラーが再試行可能な場合、processor は `{ retry: true }` を返します。メッセージは変更しません。

`delayMs` を設定すると、processor は再試行を通知する前に待機します。これは、すぐに再試行しても再び失敗する可能性が高い `ECONNRESET` などの一時的なネットワークエラーに役立ちます。遅延には固定のミリ秒数、またはエラー引数を使って評価される関数（たとえば指数バックオフの実装）を指定できます。

### 再試行回数の上限

`maxRetries` のデフォルトは `1` で、この processor が要求する再試行の回数を制限します。Agent も `maxProcessorRetries` で processor の再試行回数を制限します。Agent 側の上限を指定せずに error processor を設定した場合、runtime の上限は `10` です。

単一の再試行予算が必要な場合は、両方の値を同じ有限値に明示的に設定します。provider への試行回数が乗算されないよう、その呼び出しではモデルの `maxRetries` を `0` に保ってください。

### `Retry-After` の処理

再試行可能なエラーに `Retry-After` レスポンスヘッダーがある場合、processor はエラーの cause chain を通じて、大文字小文字を区別せずに delta-seconds 値と HTTP-date 値を読み取ります。そして、`delayMs` と上限が適用されたサーバー指定の遅延のうち、長いほうの時間だけ待機します。

`maxRetryAfterMs` のデフォルトは `30_000` です。上限が適用されるのは provider が指定した待機時間だけです。それより長い明示的な `delayMs` は変更されません。無効なヘッダーや期限切れのヘッダーは無視されます。

## 不明なエラーの再試行

provider のメタデータ、組み込みの OpenAI matcher、カスタム matcher のいずれにも一致しないエラーを再試行するには、`retryUnknownErrors` を設定します。不明なエラーの再試行には 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` であるため、有効にしない限り不明なエラーは再試行されません。

## 再試行の遅延

一時的なネットワークリセットを待機後に再試行するには、カスタム matcher とともに `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 matcher

`isRetryableOpenAIResponsesStreamError` は、`type: 'error'` または `type: 'response.failed'` を持つ OpenAI Responses のストリームエラーチャンクに一致します。既知の一時的な OpenAI エラーコードを再試行し、フォールバックとして `You can retry your request` のように明示的な再試行指示があるエラーも再試行します。

`StreamErrorRetryProcessor` には、この matcher がデフォルトで含まれています。import してカスタムの再試行ロジックで再利用することもできます。

## コンストラクターパラメーター

**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/ja/reference/processors/processor-interface)
- [Processors](https://mastra.zisheng.pro/ja/docs/agents/processors)