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

# StreamErrorRetryProcessor

`StreamErrorRetryProcessor` est un **Processor d'erreurs** qui relance les appels après des défaillances temporaires de l'API du LLM et du flux. Il intègre la détection des erreurs de flux OpenAI Responses et accepte des fonctions de correspondance supplémentaires pour les structures d'erreur propres aux autres Providers.

Le Processor n'est pas activé par défaut dans le cœur de Mastra. Ajoutez-le à `errorProcessors` pour les Agents qui ont besoin d'un nombre limité de nouvelles tentatives.

## Exemple d'utilisation

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

## Fonctionnement

Le Processor recherche les éléments suivants dans l'erreur et sa chaîne de causes :

- Métadonnées de nouvelle tentative du Provider : `isRetryable === true`
- Détection intégrée des erreurs de flux OpenAI Responses
- Résultats des fonctions de correspondance : toute fonction configurée qui renvoie `true`

Lorsque l'erreur autorise une nouvelle tentative, le Processor renvoie `{ retry: true }`. Il ne modifie pas les messages.

Lorsque `delayMs` est défini, le Processor attend avant de signaler une nouvelle tentative. Cette option est utile pour les erreurs réseau temporaires telles que `ECONNRESET`, pour lesquelles une nouvelle tentative immédiate risque d'échouer à nouveau. Le délai peut être un nombre fixe de millisecondes ou une fonction évaluée avec les arguments de l'erreur, par exemple pour mettre en œuvre un délai exponentiel.

### Limites des nouvelles tentatives

La valeur par défaut de `maxRetries` est `1` et limite les demandes de nouvelle tentative de ce Processor. L'Agent limite également les nouvelles tentatives des Processors au moyen de `maxProcessorRetries`. Lorsque des Processors d'erreurs sont configurés sans limite pour l'Agent, la limite de l'environnement d'exécution est fixée à `10`.

Définissez explicitement les deux valeurs sur la même limite lorsque vous avez besoin d'un budget unique de nouvelles tentatives. Conservez le paramètre `maxRetries` du modèle à `0` lors de cet appel afin d'éviter de multiplier les tentatives du Provider.

### Gestion de `Retry-After`

Pour les erreurs autorisant une nouvelle tentative et dotées d'un en-tête de réponse `Retry-After`, le Processor lit les valeurs delta-seconds et HTTP-date sans tenir compte de la casse dans la chaîne de causes de l'erreur. Il attend le plus long des deux délais entre `delayMs` et le délai limité du serveur.

La valeur par défaut de `maxRetryAfterMs` est `30_000`. Elle limite uniquement le délai d'attente fourni par le Provider. Une valeur `delayMs` explicite plus longue reste inchangée. Les en-têtes non valides ou expirés sont ignorés.

## Nouvelle tentative après des erreurs inconnues

Définissez `retryUnknownErrors` pour relancer les erreurs qui ne correspondent ni aux métadonnées du Provider, ni à la fonction de correspondance OpenAI intégrée, ni à une fonction de correspondance personnalisée. Les nouvelles tentatives après une erreur inconnue utilisent les valeurs `maxRetries` et `delayMs` du Processor. Les échecs d'autorisation connus, notamment les réponses HTTP `401` et `403`, ne font pas l'objet d'une nouvelle tentative :

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

Les politiques des fonctions de correspondance précises restent prioritaires sur les valeurs propres aux erreurs inconnues. La valeur par défaut de cette option est `false` ; les erreurs inconnues ne font donc pas l'objet d'une nouvelle tentative, sauf si vous l'activez.

## Retarder les nouvelles tentatives

Utilisez `delayMs` avec une fonction de correspondance personnalisée afin d'attendre avant de relancer une connexion après une réinitialisation temporaire du réseau :

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

## Fonction de correspondance OpenAI Responses par défaut

`isRetryableOpenAIResponsesStreamError` détecte les segments d'erreur de flux OpenAI Responses dont le champ vaut `type: 'error'` ou `type: 'response.failed'`. Il relance les codes d'erreur OpenAI temporaires connus et, à défaut, les erreurs qui contiennent une consigne explicite de nouvelle tentative telle que `You can retry your request`.

`StreamErrorRetryProcessor` inclut cette fonction de correspondance par défaut. Vous pouvez également l'importer et la réutiliser dans une logique personnalisée de nouvelle tentative.

## Paramètres du constructeur

**options** (`StreamErrorRetryProcessorOptions`): Configuration de la gestion des nouvelles tentatives.

## Propriétés

**id** (`'stream-error-retry-processor'`): Identifiant du Processor.

**name** (`'Stream Error Retry Processor'`): Nom d'affichage du Processor.

**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): Relance les erreurs de flux jusqu'à la limite de nouvelles tentatives configurée.

## Voir aussi

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