Dépanner les requêtes API

Utilisez ce guide lorsqu'une requête vers le canal API échoue avant, pendant ou après l'exécution.

401 invalid_api_key

Symptôme : {"error":{"code":"invalid_api_key","message":"Invalid or missing credentials"}}

Cause : Aucun en-tête Authorization n'a été envoyé, ou la clé est incorrecte, révoquée ou a été renouvelée. Les deux cas renvoient le même code.

Checklist :

1. Vérifiez que chaque requête porte Authorization: Bearer <clé> et que votre client HTTP ne supprime pas les en-têtes lors d'une redirection.
2. Copiez à nouveau la clé depuis la console - l'indice affiché est masqué (nx_live_••••abcd).
3. Confirmez qu'il n'y a pas d'espaces en début ou fin de la valeur stockée.
4. Confirmez que la clé appartient bien à ce canal (chaque canal possède sa propre clé).
5. Si la clé a été renouvelée récemment, mettez à jour votre service avec la nouvelle clé.

403 environment_mismatch

Symptôme : {"error":{"code":"environment_mismatch","message":"…"}}

Cause : L'environnement de la clé ne correspond pas à l'environnement du canal.

• Les clés nx_live_ fonctionnent uniquement sur les canaux de production.
• Les clés nx_test_ fonctionnent uniquement sur les canaux dev / staging.

Solution : Utilisez la clé avec l'environnement correspondant, ou créez le canal dans l'environnement correspondant.

403 origin_not_allowed

Symptôme : 403 avec un code d'erreur d'origine.

Cause : Vous utilisez une clé serveur (nx_live_ ou nx_test_) et la requête inclut un en-tête Origin, ou vous utilisez une clé publique (nx_pub_) et l'origine n'est pas dans la liste des origines autorisées du canal.

Checklist pour les clés serveur :

1. Supprimez l'en-tête Origin des appels serveur à serveur - les clés serveur ne doivent pas être utilisées depuis des contextes navigateur.

Checklist pour les clés publiques :

1. Confirmez que la requête inclut Origin: <votre_origine>.
2. Dans la console, vérifiez que la liste des origines autorisées du canal inclut l'origine exacte (ex. https://app.example.com) ou un motif à joker qui la couvre (https://*.example.com).
3. Une application mobile native n'envoie pas d'en-tête Origin : sa requête est acceptée sans configuration d'origine. Si votre client en envoie un malgré tout (webview), ajoutez cette origine. N'utilisez allowed_origins: ["*"] qu'en connaissance de cause (voir les implications de sécurité).

401 signature_required

Symptôme : {"error":{"code":"signature_required","message":"…"}}

Cause : Le canal a require_signature = true mais aucun en-tête X-Naixus-Signature n'a été envoyé.

Solution : Ajoutez l'en-tête de signature. Voir Signer les requêtes avec HMAC.

401 signature_expired

Symptôme : {"error":{"code":"signature_expired","message":"…"}}

Cause : L'horodatage t= dans l'en-tête de signature est à plus de 300 secondes de l'heure actuelle du serveur.

Checklist :

1. Vérifiez que l'horloge système de votre serveur est synchronisée avec NTP.
2. Confirmez que vous calculez t = floor(Date.now() / 1000) (secondes, pas millisecondes) au moment où la requête est envoyée - pas au démarrage ou depuis une valeur mise en cache.
3. Confirmez que vous ne réutilisez pas une signature calculée précédemment.

401 invalid_signature

Symptôme : {"error":{"code":"invalid_signature","message":"…"}}

Cause : Le digest HMAC ne correspond pas à ce que le serveur a calculé, ou l'en-tête est mal formé.

Checklist :

1. Confirmez que vous signez les octets bruts du corps tels qu'ils sont envoyés - pas une copie re-sérialisée ou formatée.
2. Confirmez que le Content-Type est application/json et que l'encodage du corps correspond (UTF-8).
3. Confirmez que vous utilisez le bon secret de signature pour ce canal. Copiez-le depuis la réponse de rotation si vous n'en êtes pas sûr (vous devrez le renouveler pour en obtenir un nouveau).
4. Confirmez que le format de l'en-tête est exactement t=<int>,v1=<hex_minuscules> sans espaces supplémentaires.
5. Exécutez le HMAC localement avec les mêmes octets de corps et comparez le digest.

Extrait de débogage (Python) :

import hashlib, hmac

body = b'...'  # octets exacts que vous envoyez
secret = '...'  # secret de signature
ts = '...'  # valeur t= que vous avez envoyée

signed = ts.encode('ascii') + b'.' + body
expected = hmac.new(secret.encode('utf-8'), signed, hashlib.sha256).hexdigest()
print('v1 attendu :', expected)

503 signing_secret_unavailable

Symptôme : {"error":{"code":"signing_secret_unavailable","message":"…"}}

Cause : Le canal a require_signature = true mais aucun secret de signature n'est actuellement stocké.

Solution : Dans la console (ou via POST /api/v1/channels/{id}/rotate-signing-secret), générez un secret de signature. Copiez et déployez la valeur retournée.

503 request_abandoned

Symptôme : {"error":{"code":"request_abandoned","message":"The original request ended before its outcome was recorded"}}

Cause : Le processus API d'origine s'est arrêté et, après la fenêtre de récupération de 10 minutes, aucune exécution récupérable ne permettait au service de déterminer le résultat.

Checklist :

1. Ne renvoyez pas immédiatement la même action métier avec une nouvelle clé.
2. Vérifiez l'effet attendu dans le système en aval : paiement, e-mail, ticket ou action d'outil personnalisée.
3. Si l'effet existe, considérez l'opération comme terminée et réconciliez son résultat dans votre application.
4. Si l'effet n'existe pas, réessayez l'opération avec une nouvelle valeur Idempotency-Key.
5. Conservez le X-Request-ID de la réponse pour le support si le résultat en aval ne peut pas être déterminé.

La clé d'origine continue de rejouer request_abandoned ; sa réutilisation ne démarre pas une nouvelle exécution.

403 http_error : API key is not authorized for this channel

Cause : La clé appartient à un canal qui n'est pas de type API - typiquement la clé nx_pub_ d'un canal Webchat utilisée sur /public/v1/api/*.

Solution : Utilisez la clé d'un canal API. Les clés widget ne servent qu'au widget webchat.

403 server_key_required

Cause : GET /public/v1/api/conversations (liste et recherche des conversations) a été appelé avec une clé publique nx_pub_.

Solution : Appelez cette route depuis votre backend avec une clé nx_live_ ou nx_test_. Une application peut lire l'historique d'une conversation dont elle connaît l'identifiant.

400 payload_validation_error

Cause : L'objet payload ne respecte pas le schéma configuré sur le canal.

Solution : Lisez error.fields : chaque entrée donne le champ et la règle en échec (required, invalid_type, invalid_option, out_of_range). Corrigez la valeur sans renvoyer d'autres champs réservés.

429 Too many requests

Symptôme : 429 avec Retry-After et {"error":{"code":"rate_limit_exceeded","message":"..."}}.

Cause : La limite du canal (3000/minute par défaut), la limite publique par IP (60/minute par défaut) ou la protection préliminaire par IP est atteinte. La limite par IP du canal ne s'applique pas aux clés serveur.

Solution : Attendez Retry-After puis réessayez avec la même Idempotency-Key. Si le trafic normal dépasse la limite, demandez à l'exploitant de la relever. Voir Limitation de débit.

404 artifact_not_found

Cause : Le fichier généré a expiré (conservé 1 heure), session_id ou artifact_id est erroné, ou le fichier appartient à un autre canal.

Solution : Téléchargez le fichier dès la fin de l'exécution, avec la clé du canal qui l'a produit. Un 404 immédiat et intermittent sur un déploiement multi-instances est à signaler à l'exploitant.

Canal introuvable (404) après une authentification réussie

Symptôme : 404 avec channel_not_bound.

Cause : Aucun flow ne sélectionne ce canal.

Solution : Dans le flow builder, ajoutez un nœud Trigger from Channel et sélectionnez le canal : la liaison est créée immédiatement. Pour un canal de production, publiez aussi le flow, sinon l'appel retourne 409 no_published_version.

Référence

Pour la référence complète des codes d'erreur, voir la référence d'API - section Erreurs.