Dépannage
Les problèmes les plus courants, leurs symptômes dans vos logs et leurs solutions.
Le SDK ne fait jamais tomber votre application : quand quelque chose ne va pas, la requête passe et un message apparaît dans vos logs, préfixé par [zarex] ou commençant par Request allowed without protection. Les messages du SDK sont en anglais : cherchez-les sur cette page.
L'application refuse de démarrer : « ipSource is required »
Avec Next.js ou Bun, hors de Vercel, Fly.io et Cloudflare Workers, Zarex ne peut pas deviner où lire l'adresse du visiteur. Indiquez ipSource : voir L'adresse IP du visiteur.
Aucune décision n'apparaît dans le journal
Vérifiez la clé
Message : « check your API key (revoked, wrong environment, or typo) ». La clé est absente, mal copiée ou révoquée. Vérifiez ZAREX_KEY sur le serveur, et que la clé appartient bien au projet affiché dans le dashboard.
Vérifiez l'adresse IP
Message : « The visitor's IP could not be determined » ou « remote address is unknown ». Zarex n'a pas trouvé l'adresse du visiteur, la requête n'a pas été vérifiée. C'est le cas de Next.js en local, ou d'un ipSource qui ne correspond pas à votre hébergement : voir L'adresse IP du visiteur.
Vérifiez que la route passe par Zarex
Le middleware ou le hook doit couvrir la route appelée. Avec Next.js, withZarex ne protège que le handler qu'il enveloppe.
Les décisions apparaissent dans le journal quelques secondes après les requêtes.
Tous mes visiteurs sont bloqués ensemble par la limite de débit
Tous vos visiteurs semblent venir de la même adresse : celle de votre proxy. Messages possibles : « every visitor will look like the proxy's address », « The engine received a private/local/shared IP address ». Réglez ipSource (ou trust proxy avec Express) selon votre hébergement.
Si le réglage est bon mais que beaucoup d'utilisateurs partagent une adresse (réseau mobile, Wi-Fi d'entreprise), limitez par compte avec characteristics : voir Ne dépendez pas que de l'adresse IP.
Une attaque passe alors que la règle est active
- La règle est-elle en
DRY_RUN? Elle journalise mais ne bloque jamais. - L'attaque est-elle dans le corps de la requête ? Activez
inspectBody. Avec Express, placez Zarex aprèsexpress.json(); avec Fastify, utilisez le hookpreHandler, pasonRequest. - Dans un cookie ? Activez
inspectCookies. - La requête a-t-elle été vérifiée ? Si la décision est
degraded, Zarex n'a pas pu décider : voir les sections précédentes.
Un vrai visiteur est bloqué
Demandez-lui l'identifiant de la décision (si vous le renvoyez dans onDeny), ou cherchez son adresse dans le journal : le détail indique quelle règle a bloqué, et pourquoi. Selon le cas :
- passez la règle en
DRY_RUNle temps de l'ajuster ; - pour le Shield, réglez
thresholdaprès avoir observé votre trafic ; - pour un filtre, ajoutez une condition
ALLOW; - pour la validation d'e-mail, ajoutez le domaine à
allowDomains.
« your plan's monthly quota is used up »
Le quota mensuel de votre formule est atteint : les requêtes passent sans être analysées jusqu'au mois suivant. Voir Compte et quota.
« the engine failed repeatedly; calls are paused briefly »
Zarex n'a pas répondu plusieurs fois de suite : le SDK laisse passer les requêtes sans attendre pendant une courte pause, puis réessaie. Votre site reste en ligne. Si le message persiste, vérifiez que votre serveur peut joindre Internet en HTTPS.
Le délai d'attente
Par défaut, le SDK attend la décision 500 ms au plus, puis laisse passer la requête. Si votre serveur est loin ou sur un réseau lent, et que vous voyez souvent des décisions degraded, augmentez timeoutMs.