Troubleshooting

Symptôme :j'ouvre mon HTML local en double-cliquant → la bulle Gilbert n'apparaît pas. Console du navigateur : violation frame-ancestors.

Cause : le CSP frame-ancestorsde Gilbert n'autorise que les domaines Solve HTTPS et http://localhost:*. Les origines file:// sont rejetées par le navigateur, l'iframe reste blanche.

Fix : servir le fichier via un serveur HTTP local, puis ouvrir http://localhost:PORT/votre-fichier.html. Trois exemples au choix :

# Python (présent par défaut sur macOS/Linux)
python3 -m http.server 8000

# Node (zéro install, npx télécharge à la volée)
npx serve

# PHP
php -S localhost:8000

Symptôme :l'iframe est présente dans le DOM mais reste vide. Console du navigateur : erreurs CSP ou X-Frame-Options.

Cause probable :votre page parente a un CSP qui bloque l'origine Gilbert.

Fix : ajoutez Gilbert à frame-src.

Content-Security-Policy:
  frame-src https://gilbert.solveholding.com;

Détails complets sur la page Embed iframe → Headers CSP.

Symptôme : Gilbert répond 401 avec { error: 'invalid_signature' } dès que le token est consommé.

Causes les plus fréquentes :

• Le secret côté votre backend a un retour à la ligne ou un espace invisible (copy-paste depuis un PDF). Fix : trim, vérifier la longueur exacte.
• Vous signez avec HS512 au lieu de HS256. Gilbert n'accepte que HS256 en v1.
• Le secret a été rotaté côté Gilbert et pas côté votre backend. Vérifiez l'admin Gilbert (timestamp de dernière rotation).

Symptôme : tout marchait, et puis 401au bout d'un moment.

Cause : le claim exp est dépassé.

Fix : implémenter une route refresh côté votre backend (exemple ici). L'iframe Gilbert poll cette route à 80% du TTL et swap le token sans interruption.

Cause moins fréquente : votre serveur a un clock skewimportant. Gilbert tolère 30s de drift, au-delà le token est rejeté même s'il vient d'être généré.

Symptôme : votre endpoint webhook reçoit les events mais le calcul HMAC ne match jamais celui du header X-Gilbert-Signature.

Cause #1 : la plus fréquente :vous signez le body JSON parsé puis re-sérialisé, au lieu du body brut. La sérialisation peut différer (ordre des clés, espaces) et l'HMAC change.

Cause #2 : vous comparez avec === au lieu de timingSafeEqual: ça marche, mais c'est une faille de sécurité (timing attack). Voir Webhooks → Vérifier la signature.

Symptôme : tout marche en prod, rien en dev local.

Cause : Gilbert ne peut pas appeler http://localhost. Vous devez exposer votre serveur dev via un tunnel public.

# Avec ngrok (rapide)
ngrok http 3000
# → enregistrez https://abcd.ngrok-free.app dans la console Gilbert

# Avec cloudflared (gratuit, sans signup)
cloudflared tunnel --url http://localhost:3000

Symptôme : en appelant /api/chat depuis votre app sur un domaine différent, le navigateur bloque la requête (CORS preflight failed).

Fix : ne pas appeler gilbert.solveholding.com/api/*depuis votre frontend. C'est un endpoint serveur-à-serveur. Côté navigateur, utilisez l'iframe embed (pas de CORS, communication via postMessage).

Symptôme : certaines requêtes reçoivent 429 avec un header Retry-After.

Limites par défaut :60 req/min/session, 600 req/h/tenant. Pour des charges supérieures, contactez-nous - c'est ajustable.

Fix court terme : respecter Retry-After, espacer les requêtes côté votre backend.

Écrivez-nous via solveholding.com/#contact en incluant :

• Votre workspace_id (ou tenantdans l'ancien vocabulaire) et le product_context
• Un timestamp ISO de l'incident
• Le request_id renvoyé en header X-Request-ID (présent sur toutes les réponses, y compris les erreurs)