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.
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
- L'envoi renvoie 403 pour un droit manquant
- L'envoi renvoie 402
- L'envoi renvoie 400
- L'envoi renvoie 413
- Le scan se termine en ERROR
- Le webhook n'arrive jamais
- La signature du webhook est refusée
- La lecture d'un scan renvoie 404
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 :
- Vérifiez l'en-tête :
x-api-key: sk_…pour une clé,Authorization: Bearer …pour un jeton. - 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 :
callbackUrlcommence parhttps://(une URLhttp://est refusée).callbackSecretfait 64 caractères au plus.- La clé API est rattachée à une application, et pas seulement à un client.
- 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 :
- Lisez
GET /api/antivirus/scans/{id}et sonerrorMessage. - Pour un fichier volumineux, demandez à l'utilisateur un fichier plus léger ou découpé.
- 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 :
callbackSecretn'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
2xxen 10 secondes lors des trois tentatives ; - votre endpoint n'est pas joignable depuis Internet (réseau privé, pare-feu, certificat invalide).
Solution :
- Vérifiez dans le détail du scan que
callbackUrlest bien renseigné et que le statut estCLEANouINFECTED. - Testez votre endpoint depuis l'extérieur de votre réseau avec un
curl -X POST. - 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 :
- Calculez le HMAC sur le corps brut (
express.raw()), pas sur un objet JSON ré-sérialisé. - Utilisez exactement le
callbackSecretenvoyé avec ce scan. - 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.