Errores

Metered API-key responses are JSON. On failure, branch on HTTP status, then read error.

Typical envelope:

{
  "success": false,
  "error": "<human-readable message>"
}

Some handlers (especially TikTok Shop) may use { "error": "<code>", "message": "..." } with HTTP status set. Always check status first.

Status codes#

If a reverse proxy returns 414 URI demasiado largo, switch large TikTok filter sets to PUBLICAR JSON. WinningHunter’s Standard API proxy does not emit 414 itself.

Two kinds of 429#

Rate limit (60 requests / minute / user) — no créditos object:

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

Credit exhaustion — includes créditos (and usually purchase):

{
  "success": false,
  "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
  "credits": {
    "used": 100,
    "limit": 100,
    "remaining": 0,
    "addon_remaining": 0,
    "total_remaining": 0
  },
  "purchase": { "url": "https://…/checkout-api-credits?credits=…" }
}

Branch on presence of créditos. Rate-limit 429 is often retryable after a short wait; credit exhaustion needs add-ons or the next monthly reset.

Handling pattern#

async function whFetch(path, init = {}) {
  const res = await fetch(`${ORIGIN}${path}`, {
    ...init,
    headers: { 'X-API-Key': process.env.WH_API_KEY, ...(init.headers || {}) },
  });
  let body = null;
  try { body = await res.json(); } catch { /* non-JSON */ }
  if (res.ok) return body;

  const error = (body && (body.error || body.message)) || res.statusText;
  if (res.status === 429) {
    const err = new Error(error);
    err.retryable = !(body && body.credits);
    throw err;
  }
  throw new Error(`HTTP ${res.status}: ${error}`);
}

Notes#

• Guard errors (401, 403 plan gate, limit 429, catch 500) use the éxito: falso envelope from the Standard API proxy.
• TikTok Shop explore/count can also return 403 insufficient_credits for the daily TikTok search quota — that is separate from the programmatic monthly pool (GET /api/v1/credits).
• Some TikTok Shop / dashboard handlers return business flags under HTTP 200 — read that endpoint’s schema.
• Soft handler failures (JSON error body without an uncaught exception) still consume the 1 programmatic credit already charged by the proxy.
• HTML instead of JSON usually means wrong host, proxy error page, or a session-only path. See Troubleshooting.

Related#