Dépannage

Un guide axé sur les symptômes. Repérez le problème que vous rencontrez à gauche, puis suivez les instructions de dépannage à droite.

401 Accès non autorisé — {"success": false, "error": "Unauthorized"}#

Le serveur proxy n'a pas pu attribuer votre requête à un utilisateur.

• Vérifiez le nom de l'en-tête. Il doit être Clé X-API (sans distinction de majuscules et minuscules) ou Authorization: Bearer <key>. Noms personnalisés (Clé API, X-Auth, etc.) ne sont pas analysés.
• Si vous utilisez Autorisation, la valeur doit commencer par Au porteur (avec un espace). Authorization: <key> à lui seul pas correspondance.
• Les espaces, les guillemets et les sauts de ligne superflus dans la valeur de la clé entraîneront tous un échec. Affichez la clé juste avant la requête pour vérifier qu'elle ne contient pas d'éléments indésirables.
• La clé était peut-être régénéré depuis votre dernière copie. Les anciennes clés cessent immédiatement de fonctionner lors de la régénération. Récupérez une nouvelle valeur à partir de /api.
• Solution de secours pour les paramètres de requête ?api_key= Cela fonctionne, mais assurez-vous que votre client HTTP l'encode correctement en URL.

403 Accès interdit — abonnement / accès#

La clé a été reconnue, mais l'accès à l'API n'est pas activé pour le compte de facturation associé à cette clé.

• Connectez-vous à WinningHunter et vérifiez que votre forfait et vos informations de facturation sont corrects, et que l'accès à l'API est bien inclus pour votre organisation.
• Si l'accès vient d'être acheté, veuillez patienter un instant puis réessayer ; les données de session mises en cache dans le navigateur n'ont pas le même impact sur les appels via la clé API.
• Pour les comptes d'équipe, demandez à votre administrateur de vérifier que le compte ou l'organisation dispose d'un accès à l'API.

404 — Point de terminaison inconnu de TikTok Shop#

Le chemin est enregistré, mais le gestionnaire sous-jacent ne figure pas dans la liste blanche publique.

• Assurez-vous d'appeler /api/v1/tiktok-shop/... (le /api/v1/ le préfixe a son importance). Le simple /api/tiktok-shop/... Il s'agit de l'URL de session du tableau de bord, qui n'accepte pas les clés API.
• Vérifiez le chemin d'accès dans la documentation de l'API et dans le guide thématique correspondant (TikTok Shop, bibliothèque publicitaire Meta, Brands, etc.).
• Les barres obliques finales sont importantes : respectez scrupuleusement ce qui est indiqué dans la documentation (pas de barre oblique finale, sauf indication contraire).

404 — Non trouvé (HTML ou générique)#

Le routeur n'a jamais répondu à la requête.

• Verbe « vérifier » : de nombreux terminaux n'acceptent que OBTENIR ou seulement PUBLICATION; quelques-uns acceptent les deux (GET ou POST). Un verbe incorrect dans la bonne URL renvoie une erreur 404, et non une erreur 405.
• Paramètres du chemin : /api/v1/tiktok-shop/videos/{id} nécessite {id} pour correspondre [A-Za-z0-9_-]+. Identifiants avec : ou . ne s'achemine pas.

429 — Limite de débit vs épuisement du crédit#

Deux cas distincts ont le même statut.

Vous pouvez lever toute ambiguïté par programmation en vérifiant la présence de générique élément dans le corps JSON — seuls les codes d'erreur 429 liés à l'épuisement du crédit le contiennent.

414 URL trop longue#

Vous avez envoyé un OBTENIR avec une chaîne de requête très longue (par exemple, des dizaines d'identifiants de catégorie).

• Passer à PUBLICATION JSON. Explorer/répertorier les routes TikTok Shop qui acceptent les requêtes POST en fusionnant les mêmes paramètres provenant du corps JSON avec la chaîne de requête (voir Filtres de TikTok Shop).

curl -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/products/explore" \
  -d '{"country":"US","period":"30d","category_ids":["..."],"limit":100}'

Erreur 500 du serveur interne#

Le proxy a détecté une exception non gérée et répond par {"success": false, "error": "Internal server error"}.

• Remarque : cet échec n'utilise pas votre quota mensuel (il est automatiquement remboursé). Continuez à utiliser la stratégie de repli — des erreurs 500 répétées indiquent généralement une entrée incorrecte ou un bug en amont.
• Réessayez en utilisant un délai d'attente exponentiel ; si la même charge utile renvoie systématiquement un code d'erreur 500, enregistrez la requête (clé masquée) et contactez le service d'assistance.
• JSON mal formé, incorrect pays des codes ou des valeurs numériques non valides apparaissent parfois sous la forme de 500 provenant de gestionnaires de profondeur — vérifier la validité du corps par rapport à Filtres de TikTok Shop ou le guide correspondant.

« Je reçois du code HTML, pas du JSON »#

Ce n'est pas l'application qui pose problème : c'est un intermédiaire qui renvoie une page d'erreur.

• Vérifiez votre origine ({origine} (voir la documentation). Une faute de frappe, un schéma manquant ou une panne régionale du CDN entraîneront tous l'affichage du code HTML.
• Vérifiez que /api/v1/tiktok-shop/crédits (ou tout autre point de terminaison) renvoie du JSON lorsqu'il est appelé depuis la même machine via curl -i vous voyez donc les en-têtes.
• Si un mandataire d'entreprise procède à une réécriture Autorisation en-têtes, passer à Clé X-API (moins souvent déformé).

Résultats décevants ou surprenants#

• Les produits / boutiques ne comportent que très peu de lignes. Tu as probablement mélangé période avec date_de_début / date_de_fin. Voir Plages horaires — passer seulement période sur les points de vente de TikTok Shop.
• pays est défini par défaut sur ÉTATS-UNIS. Veillez à toujours le définir explicitement pour les requêtes hors États-Unis ; sinon, vous obtiendrez des données américaines même si les filtres semblent corrects.
• Filtrer les alias. chiffre d'affaires minimum sur 30 jours et chiffre d'affaires minimum signifient la même chose dans les magasins ; min_gmv_30j et chiffre d'affaires minimum sont des pseudonymes utilisés par des créateurs ou des boutiques. Le Référence des filtres répertorie le nom canonique et les alias de chaque entité.
• non défini chaînes. Certains SDK clients sérialisent les valeurs non définies sous forme de littéral « indéfini » — le serveur les ignore, donc un filtre manquant ne provoquera pas de plantage, mais il n'appliquera rien non plus. Vérifiez la requête que votre client a réellement envoyée.

« J'appelle /api/tiktok-shop/... et être redirigé vers /connexion"#

Ce chemin est le session route — cela nécessite des cookies de navigateur. Avec une clé API, vous devez appeler /api/v1/tiktok-shop/... au lieu de cela.

« Mon équipe ne peut pas utiliser ma clé »#

Chaque coéquipier peut créer une clé à partir de /api tant que vous êtes connecté. L'utilisation doit respecter les règles de votre organisation au sein du produit ; si quelqu'un parvient tout de même à 403, faites en sorte que votre admin Vérifier le forfait et les droits d'accès à l'API pour ce compte.

Vérification de la validité de votre intégration#

Passez en revue cette liste de contrôle lorsque quelque chose ne colle pas :

1. Auteur : curl -i -H "X-API-Key: $WH_API_KEY" {origin}/api/v1/tiktok-shop/credits retours 200.
2. Formule : le compte affiche les droits d'accès à l'API dans le tableau de bord (Formule / Facturation).
3. Quota : les crédits restants la valeur ci-dessus est supérieure à 0.
4. Débit : ne dépassez pas environ 50/min — prévoyez une marge de 10/min.
5. Chemin d'accès : l'URL se trouve dans la documentation de l'API ou dans le guide correspondant.
6. Le comparatif entre les méthodes GET et POST correspond à la documentation.
7. Filtres : pour les dates, utilisez le mécanisme approprié en fonction des plages horaires; pour les noms de filtres, utilisez les formes canoniques ou les alias documentés pour chaque entité.

Si les sept tests sont réussis et que le comportement semble toujours anormal, capturez une paire requête/réponse (en masquant la clé) et envoyez-la au service d'assistance.