# 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](#lenvoi-renvoie-401)
- [L'envoi renvoie 403 pour un droit manquant](#lenvoi-renvoie-403-pour-un-droit-manquant)
- [L'envoi renvoie 402](#lenvoi-renvoie-402)
- [L'envoi renvoie 400](#lenvoi-renvoie-400)
- [L'envoi renvoie 413](#lenvoi-renvoie-413)
- [Le scan se termine en ERROR](#le-scan-se-termine-en-error)
- [Le webhook n'arrive jamais](#le-webhook-narrive-jamais)
- [La signature du webhook est refusée](#la-signature-du-webhook-est-refusée)
- [La lecture d'un scan renvoie 404](#la-lecture-dun-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** :
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](/v1.0/antivirus/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](/v1.0/credits), 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](/v1.0/antivirus/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](/v1.0/antivirus/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.
