Fehlerbehebung

A symptom-first reference. Match the response you’re seeing, then apply the fix.

401 Nicht autorisiert#

{"success": false, "error": "Unauthorized"} — the proxy could not resolve your request to a user.

• Confirm the header name: 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).
• Whitespace, quoting, and stray newlines in the key value all fail.
• Der Schlüssel könnte gewesen sein wiederhergestellt. Old keys stop immediately — copy a fresh value from /api.
• Ausweichlösung für Abfrageparameter ?api_key= works; URL-encode it correctly.

403 Zugriff verweigert#

The key was recognized, but API access is not enabled for that billing account.

• Confirm plan / billing includes API access.
• On team accounts, ask an admin to confirm the org seat has API access.

404 — Unknown TikTok Shop endpoint#

Path is registered, but the handler isn’t in the public allowlist.

• Call /api/v1/tiktok-shop/.... Bare /api/tiktok-shop/... is session-only and won’t accept API keys.
• Match the path exactly (no trailing slash unless documented).

404 — Not Found#

Der Router hat die Anfrage nie bearbeitet.

• Verben prüfen: Viele Endpunkte akzeptieren nur HOLEN oder nur BEITRAG.
• Path IDs for videos must match [A-Za-z0-9_-]+.

429 — rate limit vs credits#

Credit-exhaustion 429s include a Im Abspann object; rate-limit 429s do not.

414 URL zu lang#

Switch large filter sets to BEITRAG JSON.

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#

{"success": false, "error": "Internal server error"} — credits for that call are refunded.

• Retry with backoff; if the same payload always 500s, contact support with a redacted request.
• Sanity-check bodies against TikTok Shop filters.

HTML instead of JSON#

• Verify {Quelle} (scheme + host).
• Bevorzugen X-API-Schlüssel if a corporate proxy strips Berechtigung.

Leere oder überraschende Ergebnisse#

• Don’t mix Zeitraum mit Startdatum / Enddatum on TikTok Shop — see Zeitfenster.
• Set Land explicitly (default is USA).
• Check filter aliases in TikTok Shop filters.

Session path redirect to /login#

Sanity checklist#

1. curl -i -H "X-API-Key: $WH_API_KEY" {origin}/api/v1/credits → 200
2. Dashboard shows API access on the plan
3. verbleibende Credits (oder total_remaining) > 0
4. Under ~50 requests/min
5. Path + verb match the docs

Related#