Fehlerbehebung

Ein Leitfaden, der sich an den Symptomen orientiert. Suchen Sie das bei Ihnen auftretende Problem auf der linken Seite und befolgen Sie die Lösungsanleitung auf der rechten Seite.

401 Nicht autorisiert — {"success": false, "error": "Unauthorized"}#

Der Proxy konnte Ihre Anfrage nicht an einen Benutzer weiterleiten.

• Überprüfen Sie den Namen des Kopfzeilenfelds. Er muss X-API-Schlüssel (Groß-/Kleinschreibung wird nicht berücksichtigt) oder Authorization: Bearer <key>. Benutzerdefinierte Namen (API-Schlüssel, X-Auth, usw.) werden nicht analysiert.
• Wenn Sie Berechtigung, muss der Wert mit Inhaber (mit einem Leerzeichen). Authorization: <key> allein tut nicht Übereinstimmung.
• Leerzeichen, Anführungszeichen und überflüssige Zeilenumbrüche im Schlüsselwert führen zu Fehlern. Gib den Schlüssel unmittelbar vor der Anfrage aus, um sicherzustellen, dass er fehlerfrei ist.
• Der Schlüssel könnte gewesen sein wiederhergestellt seitdem du ihn zuletzt kopiert hast. Alte Schlüssel funktionieren nach der Neugenerierung sofort nicht mehr. Rufe einen neuen Wert von /api.
• Ausweichlösung für Abfrageparameter ?api_key= Das funktioniert, aber stellen Sie sicher, dass Ihr HTTP-Client die URL korrekt umkodiert.

403 Zugriff verweigert — Abonnement / Zugang#

Der Schlüssel wurde erkannt, aber für das mit diesem Schlüssel verknüpfte Abrechnungskonto ist der API-Zugriff nicht aktiviert.

• Melden Sie sich bei WinningHunter an und überprüfen Sie Ihren Tarif sowie die Rechnungsdaten und stellen Sie sicher, dass der API-Zugang für Ihre Organisation enthalten ist.
• Falls der Zugriff gerade erst erworben wurde, warten Sie einen Moment und versuchen Sie es erneut; zwischengespeicherte Sitzungsdaten im Browser wirken sich nicht in gleicher Weise auf API-Key-Aufrufe aus.
• Bei Team- Konten bitten Sie Ihren Administrator, zu überprüfen, ob der Benutzer oder die Organisation über API-Zugriff verfügt.

404 — Unbekannter TikTok-Shop-Endpunkt#

Der Pfad ist registriert, aber der zugehörige Handler ist nicht in der öffentlichen Zulassungsliste enthalten.

• Vergewissern Sie sich, dass Sie anrufen /api/v1/tiktok-shop/... (das /api/v1/ Das Präfix ist entscheidend). Das bloße /api/tiktok-shop/... ist die Sitzungs-URL des Dashboards und akzeptiert keine API-Schlüssel.
• Vergleichen Sie den Pfad in der API-Referenz und im entsprechenden Themenleitfaden (TikTok Shop, Meta-Anzeigenbibliothek, Brands usw.).
• Abschließende Schrägstriche sind wichtig – halten Sie sich genau an die Angaben in der Dokumentation (kein abschließender Schrägstrich, sofern nicht anders angegeben).

404 — Nicht gefunden (HTML oder allgemein)#

Der Router hat die Anfrage nie bearbeitet.

• Verben prüfen: Viele Endpunkte akzeptieren nur HOLEN oder nur BEITRAG; einige akzeptieren beides (GET oder POST). Ein falsches Verb auf dem richtigen Pfad führt zu einem 404-Fehler, nicht zu einem 405-Fehler.
• Pfadparameter: /api/v1/tiktok-shop/videos/{id} erfordert {id} passend [A-Za-z0-9_-]+. IDs mit : oder . wird nicht weitergeleitet.

429 — Ratenbegrenzung vs. Krediterschöpfung#

Zwei unterschiedliche Fälle haben denselben Status.

Sie können die Mehrdeutigkeit programmgesteuert auflösen, indem Sie prüfen, ob das Im Abspann Objekt im JSON-Body – nur 429-Fehlermeldungen wegen aufgebrauchter Guthaben enthalten es.

414 URL zu lang#

Du hast eine HOLEN mit einem sehr langen Abfrage-String (z. B. Dutzende von Kategorie-IDs).

• Wechseln zu BEITRAG JSON. Ermitteln/zählen Sie TikTok-Shop-Routen, die POST-Anfragen akzeptieren und dabei die gleichen Parameter aus dem JSON-Body mit dem Abfrage-String zusammenführen (siehe TikTok Shop-Filter).

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}'

500 Interner Serverfehler#

Der Proxy hat eine nicht abgefangene Ausnahme abgefangen und antwortet mit {"success": false, "error": "Internal server error"}.

• Hinweis: Dieser Fehler wird nicht von Ihrem monatlichen Kontingent abgezogen (er wird automatisch gutgeschrieben). Verwenden Sie dennoch die Backoff-Funktion – wiederholte 500-Fehler deuten in der Regel auf fehlerhafte Eingaben oder einen Fehler auf der übergeordneten Ebene hin.
• Versuchen Sie es erneut mit exponentiellem Backoff; sollte bei derselben Nutzlast jedes Mal ein 500-Fehler auftreten, erfassen Sie die Anfrage (Schlüssel unkenntlich gemacht) und wenden Sie sich an den Support.
• Fehlerhaftes JSON, fehlerhaft Land Codes oder ungültige Zahlen tauchen manchmal als 500 von Deep Handlern – den Text auf Korrektheit prüfen TikTok Shop-Filter oder den entsprechenden Leitfaden.

„Ich erhalte HTML zurück, nicht JSON“#

Du greifst nicht auf die Anwendung zu – es gibt einen Zwischenschritt, der eine Fehlerseite zurückgibt.

• Überprüfen Sie Ihre Herkunft ({Quelle} (siehe Dokumentation). Ein Tippfehler, ein fehlendes Schema oder ein CDN mit regionalem Ausfall führen dazu, dass HTML ausgeliefert wird.
• Überprüfen Sie, ob /api/v1/tiktok-shop/credits (oder ein beliebiger anderer Endpunkt) gibt JSON zurück, wenn er von demselben Rechner aus über curl -i So siehst du die Überschriften.
• Wenn ein Unternehmensproxy umgeschrieben wird Berechtigung Kopfzeilen, wechseln zu X-API-Schlüssel (wird seltener falsch geschrieben).

Leere oder überraschende Ergebnisse#

• Die Produkt- und Shop-Seiten enthalten nur sehr wenige Zeilen. Du hast wahrscheinlich Zeitraum mit Startdatum / Enddatum. Siehe Zeitfenster — überspringen nur Zeitraum auf den Endpunkten von TikTok Shop.
• Land Standardmäßig USA. Stellen Sie dies bei Abfragen außerhalb der USA immer explizit ein; andernfalls werden Ihnen US-Daten angezeigt, auch wenn die Filter richtig eingestellt sind.
• Filter-Aliase. min_umsatz_30_Tage und Mindestumsatz bedeuten in Geschäften dasselbe; min_gmv_30d und Mindestumsatz sind Aliasnamen für Urheber/Shops. Die Filterübersicht listet den kanonischen Namen und die Aliase pro Entität auf.
• undefiniert Zeichenfolgen. Einige Client-SDKs serialisieren undefinierte Werte als Literal „undefiniert“ — Der Server filtert diese heraus, sodass ein fehlender Filter zwar keinen Absturz verursacht, aber auch keine Filterung vornimmt. Überprüfen Sie die Anfrage, die Ihr Client tatsächlich gesendet hat.

„Ich rufe an“ /api/tiktok-shop/... und dann weitergeleitet zu /login"#

Dieser Weg ist der Sitzung Route – hierfür sind Browser-Cookies erforderlich. Mit einem API-Schlüssel müssen Sie /api/v1/tiktok-shop/... stattdessen.

„Mein Team kann meinen Schlüssel nicht verwenden“#

Jeder Teamkollege kann einen Schlüssel erstellen aus /api solange Sie angemeldet sind. Die Nutzung richtet sich nach den Regeln Ihrer Organisation im Produkt – falls jemand dennoch 403, lassen Sie Ihr Admin Überprüfen Sie den Tarif und den API-Zugriff für diesen Account.

Überprüfung der Integration auf Fehlerfreiheit#

Gehen Sie diese Checkliste durch, wenn etwas nicht stimmt:

1. Autor: curl -i -H "X-API-Key: $WH_API_KEY" {origin}/api/v1/tiktok-shop/credits Ergebnisse 200.
2. Tarif: Der API-Zugriff wird im Dashboard des Kontos angezeigt (Tarif / Abrechnung).
3. Kontingent: der verbleibende Credits von oben ist > 0.
4. Drehzahl: Du solltest nicht mehr als ca. 50 U/min fahren – lass dir 10 U/min Spielraum.
5. Pfad: Die URL finden Sie in der API-Referenz oder im entsprechenden Themenleitfaden.
6. Verb: GET vs. POST entspricht der Dokumentation.
7. Filter: Bei Datumsangaben ist der für die jeweiligen Zeitfenster vorgesehene Mechanismus zu verwenden; bei Filternamen sind die für die jeweilige Entität dokumentierten kanonischen Formen bzw. Aliasformen zu verwenden.

Wenn alle sieben Tests bestanden sind und das Verhalten dennoch nicht korrekt erscheint, erfassen Sie ein Anfrage-Antwort-Paar (wobei der Schlüssel unkenntlich gemacht wird) und senden Sie es an den Support.