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

# StreamErrorRetry프로세서

`StreamErrorRetryProcessor`은**오류 프로세서**일시적인 LLM API 및 스트림 오류를 재시도합니다. OpenAI 응답 스트림 오류에 대한 기본 일치 기능이 포함되어 있으며 다른 공급자별 오류 형태에 대한 추가 일치자를 지원합니다.

이 프로세서는 코어에서 기본적으로 활성화되지 않습니다. 제한된 재시도 처리가 필요한 Agent의 `errorProcessors`에 추가하세요.

## 사용예

`errorProcessors`에 `StreamErrorRetryProcessor`를 추가하세요.

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

## 작동 원리

프로세서는 다음 사항에 대해 오류와 원인 체인을 확인합니다.

- 공급자 재시도 메타데이터:`isRetryable === true`
- 내장된 OpenAI 응답 스트림 오류 일치
- 일치자 결과: 반환하는 구성된 모든 일치자`true`

오류를 재시도할 수 있으면 프로세서가 `{ retry: true }`를 반환합니다. 메시지는 변경하지 않습니다. `delayMs`가 설정되면 프로세서는 재시도 신호를 보내기 전에 기다립니다. 즉시 재시도하면 다시 실패할 가능성이 높은 `ECONNRESET` 같은 일시적 네트워크 오류에 유용합니다. 지연 시간은 고정된 밀리초 값이나 오류 인수를 사용해 평가되는 함수(예: 지수 백오프 구현)로 지정할 수 있습니다.

### 재시도 한도

`maxRetries`의 기본값은 `1`이며 이 프로세서가 요청할 수 있는 재시도 횟수를 제한합니다. Agent도 `maxProcessorRetries`를 사용하여 프로세서 재시도를 제한합니다. Agent 제한 없이 오류 프로세서를 구성하면 런타임 상한은 `10`입니다. 하나의 재시도 예산을 사용하려면 두 값을 모두 명시적으로 동일한 제한 값으로 설정하세요. Provider 시도 횟수가 배가되지 않도록 해당 호출에서 Model의 `maxRetries`를 `0`으로 유지하세요.

### `Retry-After`손질

재시도 가능한 오류에 `Retry-After` 응답 헤더가 있으면 프로세서는 오류 원인 체인을 따라 대소문자를 구분하지 않고 delta-seconds 및 HTTP-date 값을 읽습니다. `delayMs`와 제한된 서버 지연 중 더 긴 시간만큼 기다립니다. `maxRetryAfterMs`의 기본값은 `30_000`입니다. Provider가 제공한 대기 시간에만 상한을 적용합니다. 더 긴 명시적 `delayMs`는 변경되지 않습니다. 유효하지 않거나 만료된 헤더는 무시됩니다.

## 알 수 없는 오류 재시도

Provider 메타데이터, 기본 제공 OpenAI 매처 또는 사용자 지정 매처와 일치하지 않는 오류를 재시도하려면 `retryUnknownErrors`를 설정하세요. 알 수 없는 오류 재시도에는 프로세서 수준의 `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 응답 일치자

`isRetryableOpenAIResponsesStreamError`는 `type: 'error'` 또는 `type: 'response.failed'`인 OpenAI 응답 스트림 오류 청크와 일치합니다. 알려진 일시적 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/ko/reference/processors/processor-interface)
- [프로세서](https://mastra.zisheng.pro/ko/docs/agents/processors)