Aller au contenu
Cercle IA Tech · Intégration Un site du réseau Cercle IA Tech

Guide

Cloudflare Queues : réessais et file d'échecs

Cloudflare Queues pour un traitement IA : lots, ack et retry, 3 réessais par défaut, file des messages en échec, conservation de 4 jours.

Mis à jour le

Quand un traitement d'IA échoue au milieu d'une intégration (modèle indisponible, limite d'appels atteinte, CRM qui ne répond pas), il faut décider ce qu'on fait du message : le perdre, le rejouer tout de suite, ou le rejouer plus tard. Cloudflare Queues, la file de messages de la plateforme Cloudflare, fournit les trois réglages. Cette page résume ce que dit sa documentation, lue le 16/11/2026. Elle suppose que vous avez déjà une file entre vos événements entrants et votre appel au modèle, comme le décrit la page webhook et IA.

Si le consommateur de la file appelle un assistant, la documentation API d’ALMA permet d’examiner les réponses attendues. Définissez ce qui peut être rejoué sans effet supplémentaire avant de configurer les tentatives de Queues.

Le lot : taille et délai

Un consommateur (le programme qui lit la file) reçoit les messages par lots. Deux réglages décident du moment de la livraison :

Réglage Valeur par défaut Plage permise
max_batch_size 10 messages 1 à 100
max_batch_timeout 5 secondes 0 à 60 secondes

Le lot part dès que l'une des deux limites est atteinte. Pour un traitement IA où chaque message déclenche un appel au modèle, un petit lot limite le nombre d'appels simultanés.

Confirmer ou rejouer

Chaque message se confirme avec msg.ack() ou se renvoie en file avec msg.retry(). Les équivalents pour tout le lot sont ackAll() et retryAll(). La première instruction donnée sur un message l'emporte : un ack() ou un retry() sur un message passe avant un appel plus tardif au niveau du lot.

Point important : si un message d'un lot échoue, tout le lot est rejoué, sauf pour les messages que vous avez confirmés explicitement. Confirmez donc chaque message dès qu'il est traité, sans quoi un message réussi sera traité une seconde fois. Chaque réessai compte aussi comme une lecture supplémentaire.

Les réessais et leur délai

  • Le nombre de réessais par défaut est de 3 (max_retries).
  • Un délai de réessai peut aller jusqu'à 24 heures.
  • On le fixe à l'envoi (delaySeconds sur send() ou sendBatch()), ou au réessai : par message avec msg.retry({ delaySeconds: 3600 }), par lot avec batch.retryAll({ delaySeconds: 600 }).
  • Un réglage par message ou par lot l'emporte sur le réglage de la file.

Chaque message livré porte une propriété attempts. La documentation s'en sert pour un délai exponentiel : BASE_DELAY_SECONDS = 30 et la fonction calculateExponentialBackoff(attempts, baseDelaySeconds), qui renvoie baseDelaySeconds ** attempts. Pour un appel à un modèle limité en débit, un délai qui grandit à chaque tentative évite de relancer la panne.

La file des échecs

Sans autre réglage, un message qui a épuisé ses réessais est supprimé définitivement. Pour le garder, on déclare une file des échecs (dead-letter queue) dans la configuration du consommateur, avec le paramètre dead_letter_queue, ou avec l'option --dead-letter-queue de wrangler queues consumer add.

  • Cette file se comporte comme n'importe quelle autre : on peut y écrire et la lire séparément.
  • Elle doit se trouver dans la même juridiction que la file d'origine. Si elle n'existe pas, Cloudflare la crée dans cette juridiction.
  • Pour traiter ce qu'elle contient, il faut un consommateur sur cette file.
  • Sans consommateur, les messages y restent quatre jours, puis sont supprimés.

Prévoyez donc une alerte sur cette file : un message qui y arrive est un traitement IA qui n'a pas abouti, et personne ne le saura si la file n'est pas surveillée avant la fin des quatre jours.

Ce que la documentation ne règle pas à votre place

Elle ne dit pas comment éviter qu'un message rejoué crée un doublon dans votre CRM : c'est à votre traitement d'être sûr de ne pas écrire deux fois. Elle ne dit pas non plus quelles erreurs méritent un réessai. Une limite d'appels atteinte se rejoue plus tard ; une donnée mal formée ne guérira pas, et passe mieux directement en file des échecs avec un message d'explication.

D'autres éditeurs proposent des files équivalentes, avec leurs propres valeurs. La logique reste la même : un nombre de tentatives borné, un délai croissant, un endroit où les échecs attendent un humain. La liste de contrôle de la mise en production reprend la file d'attente parmi les points à vérifier avant la bascule, et l'architecture type montre où elle se place.

La méthode générale de gestion des erreurs d'un flux est décrite sous un autre angle sur Alaisia · Intégrateurs.

Questions fréquentes

Combien de fois Cloudflare Queues réessaie-t-il un message ?

Trois fois par défaut (max_retries). La documentation recommande de garder cette valeur. Ensuite, le message est supprimé, ou envoyé dans la file des échecs si vous en avez configuré une.

Combien de temps garde-t-on les messages d'une file des échecs ?

Quatre jours quand aucun consommateur n'est branché sur cette file. Passé ce délai, ils sont supprimés.

Peut-on retarder un réessai ?

Oui, jusqu'à 24 heures, avec delaySeconds sur l'appel retry, sur un message ou sur tout le lot.

Sources

Pages consultées pour écrire cet article :

  1. https://alma.iarche.fr/fr/api-docs
  2. https://developers.cloudflare.com/queues/configuration/batching-retries/
  3. https://developers.cloudflare.com/queues/configuration/dead-letter-queues/

À lire aussi