Dépanner les erreurs d'authentification et de signature

Utilisez ce guide lorsque vos requêtes vers le canal API retournent des erreurs d'authentification ou de signature inattendues.

401 missing_api_key

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

Cause : Aucun en-tête Authorization n'a été envoyé.

Solution : Ajoutez Authorization: Bearer <clé> à chaque requête. Vérifiez que votre client HTTP ne supprime pas les en-têtes lors d'une redirection.

401 invalid_api_key

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

Cause : La clé est incorrecte, révoquée ou a été renouvelée.

Checklist :

1. Copiez à nouveau la clé depuis la console - l'indice affiché est masqué (nx_live_••••abcd).
2. Confirmez qu'il n'y a pas d'espaces en début ou fin de la valeur stockée.
3. Confirmez que la clé appartient bien à ce canal (chaque canal possède sa propre clé).
4. 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).
3. Si vous appelez depuis une application mobile native qui ne peut pas définir Origin, soit :
   • Utilisez un proxy backend avec une clé nx_live_.
   • Définissez allowed_origins: ["*"] sur le canal (lisez d'abord 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.

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

Symptôme : 404 avec channel_not_bound ou similaire.

Cause : Le canal existe mais n'est pas lié à un flow publié.

Solution : Dans le flow builder, ajoutez un nœud Trigger from Channel, sélectionnez le canal et publiez le flow.

Référence

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