Solución de problemas

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

401 Acceso no autorizado#

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

• Confirm the header name: Clave X-API (case-insensitive) o Authorization: Bearer <key>. Custom names (Api-Key, X-Auth, etc.) are not parsed.
• Si utilizas Autorización, 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 Prohibido#

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 OBTENER or only PUBLICAR.
• Path IDs for videos must match [A-Za-z0-9_-]+.

429 — rate limit vs credits#

Credit-exhaustion 429s include a créditos object; rate-limit 429s do not.

414 URI demasiado largo#

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

Error 500 del servidor interno#

{"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 Clave X-API if a corporate proxy strips Autorización.

Empty or surprising results#

• Don’t mix período con fecha_de_inicio / fecha de finalización on TikTok Shop — see Intervalos de tiempo.
• Set país explicitly (default is EE. UU.).
• 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 (o total_remaining) > 0
4. Under ~50 requests/min
5. Path + verb match the docs

Related#