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.
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
- 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.