Dépannage

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

401 Accès non autorisé#

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

• Confirm the header name: 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).
• Whitespace, quoting, and stray newlines in the key value all fail.
• La clé était peut-être régénéré. Old keys stop immediately — copy a fresh value from /api.
• Solution de secours pour les paramètres de requête ?api_key= works; URL-encode it correctly.

403 Accès interdit#

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#

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

• Verbe « vérifier » : de nombreux terminaux n'acceptent que OBTENIR ou seulement PUBLICATION.
• Path IDs for videos must match [A-Za-z0-9_-]+.

429 — rate limit vs credits#

Credit-exhaustion 429s include a générique object; rate-limit 429s do not.

414 URL trop longue#

Switch large filter sets to PUBLICATION 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}'

Erreur 500 du serveur interne#

{"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 {origine} (scheme + host).
• Prefer Clé X-API if a corporate proxy strips Autorisation.

Résultats décevants ou surprenants#

• Don’t mix période avec date_de_début / date_de_fin on TikTok Shop — see Plages horaires.
• Set pays explicitly (default is ÉTATS-UNIS).
• Check filter aliases in TikTok Shop filters.

Session path redirect to /connexion#

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. crédits restants (or total_remaining) > 0
4. Under ~50 requests/min
5. Path + verb match the docs

Related#