Troubleshooting

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

401 Unauthorized#

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

• Confirm the header name: X-API-Key (case-insensitive) or Authorization: Bearer <key>. Custom names (Api-Key, X-Auth, etc.) are not parsed.
• If you use Authorization, the value must start with Bearer (with a space).
• Whitespace, quoting, and stray newlines in the key value all fail.
• The key may have been regenerated. Old keys stop immediately — copy a fresh value from /api.
• Query-param fallback ?api_key= works; URL-encode it correctly.

403 Forbidden#

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#

The router never matched the request.

• Check verb: many endpoints accept only GET or only POST.
• Path IDs for videos must match [A-Za-z0-9_-]+.

429 — rate limit vs credits#

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

414 URI Too Long#

Switch large filter sets to POST 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 Internal Server Error#

{"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 {origin} (scheme + host).
• Prefer X-API-Key if a corporate proxy strips Authorization.

Empty or surprising results#

• Don’t mix period with start_date / end_date on TikTok Shop — see Time windows.
• Set country explicitly (default is US).
• 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. credits.remaining (or total_remaining) > 0
4. Under ~50 requests/min
5. Path + verb match the docs

Related#