StreamErrorRetryProcessor

StreamErrorRetryProcessor は、一時的な LLM API エラーとストリーム障害を再試行する error processor です。OpenAI Responses のストリームエラーに対する組み込みのマッチングを備え、他の provider 固有のエラー形式に対応する追加 matcher もサポートします。

この processor は core でデフォルトでは有効になっていません。回数制限付きの再試行処理が必要な Agent の errorProcessors に追加してください。

使用例

StreamErrorRetryProcessor を errorProcessors に追加します。

src/mastra/agents/openai-agent.ts

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 レスポンスなど、既知の認証・認可エラーは再試行されません。

src/mastra/agents/resilient-agent.ts

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 を使用します。

src/mastra/agents/resilient-agent.ts

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

再試行処理の設定。

number

StreamErrorRetryMatcher[]

boolean

number | ((args: ProcessAPIErrorArgs) => number | Promise<number>)

number

プロパティ

id:

'stream-error-retry-processor'

Processor の識別子。

name:

'Stream Error Retry Processor'

Processor の表示名。

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void

設定された再試行上限までストリームエラーを再試行します。

関連情報

• Processor interface
• Processors