Resolução de problemas

A symptom-first reference. Find the response you're seeing on the left, follow the fix on the right.

401 Acesso não autorizado — {"success": false, "error": "Unauthorized"}#

The proxy could not resolve your request to a user.

• Confirm the header name. It must be Chave X-API (case-insensitive) ou Authorization: Bearer <key>. Custom names (Api-Key, X-Auth, etc.) are not parsed.
• If you are using Autorização, the value must start with Bearer (with a space). Authorization: <key> alone does não match.
• Whitespace, quoting, and stray newlines in the key value will all fail. Print the key just before the request to confirm it's clean.
• The key may have been regenerated since you last copied it. Old keys stop working immediately on regeneration. Fetch a fresh value from /api.
• Query-param fallback ?api_key= works, but be sure your HTTP client URL-encodes it correctly.

403 Acesso negado — subscription / access#

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

• Sign in to WinningHunter and confirm plan / billing and that API access is included for your organization.
• If access was just purchased, wait a moment and retry; cached session data in the browser does not affect API-key calls the same way.
• On team accounts, ask your admin to confirm the seat or org has API access.

404 — Unknown TikTok Shop endpoint#

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

• Make sure you're calling /api/v1/tiktok-shop/... (o /api/v1/ prefix matters). The bare /api/tiktok-shop/... is the dashboard's session route and won't accept API keys.
• Cross-check the path in the API reference and the relevant topic guide (TikTok Shop, Meta ad library, Brands, …).
• Trailing slashes matter — match exactly what the docs show (no trailing slash unless documented).

404 — Não encontrado (HTML or generic)#

The router never matched the request.

• Check verb: many endpoints accept only OBTER or only POST; a few accept both (GET or POST). Wrong verb on the right path returns 404, not 405.
• Path parameters: /api/v1/tiktok-shop/videos/{id} requires {id} to match [A-Za-z0-9_-]+. IDs with : ou . won't route.

429 — rate limit vs credit exhaustion#

Two distinct cases share the same status.

You can disambiguate programmatically by checking for the créditos object in the JSON body — only credit-exhaustion 429s include it.

414 URI muito longo#

You sent a OBTER with a very large query string (e.g. dozens of category IDs).

• Switch to POST JSON. Explore/count TikTok Shop routes that accept POST merge the same parameters from a JSON body with the query string (see Filtros da TikTok Shop).

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

Erro 500 do servidor interno#

The proxy caught an uncaught exception and responds with {"success": false, "error": "Internal server error"}.

• Credits: that failure does not consume your monthly credit (it is refunded automatically). Still use backoff — repeated 500s usually mean bad input or an upstream bug.
• Retry with exponential backoff; if the same payload 500s every time, capture the request (key redacted) and contact support.
• Malformed JSON, bad país codes, or invalid numerics sometimes surface as 500 from deep handlers — sanity-check the body against Filtros da TikTok Shop or the relevant guide.

"I get HTML back, not JSON"#

You aren't hitting the application — there's an intermediary returning an error page.

• Verify your origin ({origin} in the docs). A typo, missing scheme, or a CDN with a regional outage will all serve HTML.
• Check that /api/v1/tiktok-shop/créditos (or any other endpoint) returns JSON when called from the same machine via curl -i so you see the headers.
• If a corporate proxy is rewriting Autorização headers, switch to Chave X-API (less commonly mangled).

Empty or surprising results#

• Products / shops have very few rows. You probably mixed período with start_date / end_date. See Intervalos de tempo — pass only período on TikTok Shop endpoints.
• país defaults to EUA. Always set it explicitly for non-US queries; otherwise you'll see US data even when filters look right.
• Filter aliases. receita_mínima_30_dias e receita mínima mean the same thing on shops; min_gmv_30d e receita mínima are aliases on creators/shops. The filters reference lists the canonical name and aliases per entity.
• undefined strings. A few client SDKs serialize undefined values as the literal "indefinido" — the server strips these out, so a missing filter won't crash, but it also won't apply anything. Check the request your client actually sent.

"I'm calling /api/tiktok-shop/... and getting redirected to /login"#

That path is the session route — it requires browser cookies. With an API key you must call /api/v1/tiktok-shop/... em vez disso.

"My team can't use my key"#

Each teammate can create a key from /api while signed in. Usage follows your organization’s rules in the product—if someone still gets 403, have your admin verify plan and API access for that seat.

Sanity-checking your integration#

Run this checklist when something doesn't add up:

1. Auth: curl -i -H "X-API-Key: $WH_API_KEY" {origin}/api/v1/tiktok-shop/credits devoluções 200.
2. Plan: the account shows API access in the dashboard (plan / billing).
3. Quota: o credits.remaining from above is > 0.
4. Rate: you are not running more than ~50/min — leave 10/min of headroom.
5. Path: the URL is in the API reference or the matching topic guide.
6. Verb: GET vs POST matches the docs.
7. Filters: dates use the correct mechanism per Time windows; filter names use the canonical / alias forms documented per entity.

If all seven pass and behavior still looks wrong, capture a request/response pair (with the key redacted) and send it to support.