Skip to content

Résoudre les problèmes d'analyse

Les erreurs et comportements rencontrés en intégrant l'antivirus Wakastart, avec leur cause et leur solution.

TroubleshootingDeveloper

This page has not been translated yet and is shown in French.

Cette page part de ce que vous observez : un code d'erreur, un statut qui ne bouge pas, un webhook qui n'arrive pas. Les messages sont cités tels que l'API les renvoie.

Symptômes

L'envoi renvoie 401

Cause : l'appel ne porte ni clé API valide ni jeton. Message : Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header).

Solution :

  1. Vérifiez l'en-tête : x-api-key: sk_… pour une clé, Authorization: Bearer … pour un jeton.
  2. Vérifiez que la clé n'a pas été révoquée et qu'elle commence par sk_.

L'envoi renvoie 403 pour un droit manquant

Cause : le profil de la clé ou de l'utilisateur ne porte pas le droit attendu : Droit applicatif requis : antivirus.scan à l'envoi, antivirus.read à la lecture.

Solution : ajoutez Lancer un scan antivirus ou Voir le module antivirus au profil. Voir Autoriser votre serveur.

Si le message est Access denied: token authorized party does not match the target application, le jeton a été émis pour une autre application : utilisez un jeton du realm de cette application.

L'envoi renvoie 402

Cause : le solde de crédits du client est vide, ou le client n'a pas encore de solde. Le message est Antivirus service error.

Solution : rechargez le solde depuis Crédits, puis renvoyez le fichier.

L'envoi renvoie 400

Cause : le service d'analyse refuse la demande. Le détail n'est pas renvoyé ; vérifiez dans l'ordre :

  1. callbackUrl commence par https:// (une URL http:// est refusée).
  2. callbackSecret fait 64 caractères au plus.
  3. La clé API est rattachée à une application, et pas seulement à un client.
  4. Le fichier respecte la politique d'analyse de votre client : taille, type MIME réel, extensions. Voir Quarantaine et politique.

Pour vérifier : renvoyez le même fichier sans callbackUrl ni callbackSecret. S'il passe, le problème vient du webhook ; sinon, de la clé ou de la politique.

L'envoi renvoie 413

Cause : le fichier dépasse 100 Mo.

Solution : refusez le fichier côté application. Gardez aussi en tête que seuls les fichiers de 50 Mo au plus peuvent être analysés jusqu'au bout.

Le scan se termine en ERROR

Cause : l'analyse a échoué trois fois. Le champ errorMessage du détail en donne la raison. Les causes les plus courantes :

  • fichier de plus de 50 Mo, que le moteur refuse d'examiner ;
  • analyse de plus de 30 secondes (archive très volumineuse ou très imbriquée) ;
  • indisponibilité momentanée du moteur.

Solution :

  1. Lisez GET /api/antivirus/scans/{id} et son errorMessage.
  2. Pour un fichier volumineux, demandez à l'utilisateur un fichier plus léger ou découpé.
  3. Sinon, renvoyez le fichier un peu plus tard. Ne libérez jamais un fichier dont l'analyse est en ERROR.

Le webhook n'arrive jamais

Cause possible :

  • callbackSecret n'a pas été envoyé : sans secret, aucun webhook n'est émis ;
  • le scan est en ERROR, qui ne déclenche pas de webhook ;
  • votre endpoint n'a pas répondu 2xx en 10 secondes lors des trois tentatives ;
  • votre endpoint n'est pas joignable depuis Internet (réseau privé, pare-feu, certificat invalide).

Solution :

  1. Vérifiez dans le détail du scan que callbackUrl est bien renseigné et que le statut est CLEAN ou INFECTED.
  2. Testez votre endpoint depuis l'extérieur de votre réseau avec un curl -X POST.
  3. Mettez en place une interrogation de rattrapage. Voir Suivre une analyse.

La signature du webhook est refusée

Cause : la signature est calculée sur un corps différent de celui reçu, ou avec un autre secret.

Solution :

  1. Calculez le HMAC sur le corps brut (express.raw()), pas sur un objet JSON ré-sérialisé.
  2. Utilisez exactement le callbackSecret envoyé avec ce scan.
  3. Comparez la valeur hexadécimale minuscule de X-Webhook-Signature, sans préfixe.

La lecture d'un scan renvoie 404

Cause : l'identifiant n'existe pas, ou le scan appartient à un autre client que celui de votre clé ou de votre jeton. Le message est Antivirus service error.

Solution : vérifiez que vous lisez avec une clé du même client que celle qui a envoyé le fichier.

Toujours bloqué ?

Contactez le support Wakastart avec :

  • l'identifiant du scan (id) ;
  • l'heure exacte de l'appel et le code HTTP reçu ;
  • le corps complet de la réponse d'erreur, sans votre clé API.