jackwener/OpenCLI · error · Error

AUTH_REQUIRED

AUTH_REQUIRED

Error message

AUTH_REQUIRED: ${label} API failed: ${message}

What it means

assertTikTokApiSuccess inspects status_code/statusCode in a TikTok API payload; when the code is 8 or the status message matches auth/captcha/login/permission patterns it throws an 'AUTH_REQUIRED: <label> API failed: <msg>' error. This signals the API call was rejected because the session is not authenticated or is challenged.

Source

Thrown at clis/tiktok/utils.js:254

  const text = await res.text();
  if (!res.ok) {
    throw new Error('HTTP ' + res.status + ' from ' + requestUrl + ': ' + text.slice(0, 160));
  }
  if (!text.trim()) return {};
  try {
    return JSON.parse(text);
  } catch (error) {
    throw new Error('invalid JSON from ' + requestUrl + ': ' + (error instanceof Error ? error.message : String(error)));
  }
}

function assertTikTokApiSuccess(data, label) {
  if (!data || typeof data !== 'object') return;
  const code = data.status_code ?? data.statusCode;
  if (code === undefined || code === null || Number(code) === 0) return;
  const message = cleanText(data.status_msg ?? data.statusMsg ?? data.message ?? data.msg ?? code, 240);
  if (Number(code) === 8 || /auth|captcha|login|permission|unauthori[sz]ed|forbidden/i.test(message)) {
    throw new Error('AUTH_REQUIRED: ' + label + ' API failed: ' + message);
  }
  throw new Error(label + ' API failed: ' + message);
}

function findUniversalData() {
  const scripts = Array.from(document.querySelectorAll('script'));
  for (const script of scripts) {
    const text = script.textContent || '';
    if (!text || text.length < 32) continue;
    const trimmed = text.trim();
    if (!(trimmed.startsWith('{') || trimmed.startsWith('['))) continue;
    if (
      !text.includes('webapp.user-detail') &&
      !text.includes('webapp.recommend-feed') &&
      !text.includes('webapp.live-discover') &&
      !text.includes('ItemModule') &&
      !text.includes('itemList') &&
      !text.includes('userInfo') &&

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Re-authenticate the browser session / refresh cookies and rerun the command
  2. Open tiktok.com in the automated browser and complete any captcha manually
  3. Check status_msg after the prefix for the exact permission being denied
  4. Confirm the response really contains status_code (schema change could feed wrong values)

Example fix

// before
const data = await fetchJson(url);
assertTikTokApiSuccess(data, 'user/detail');
// after
try {
  const data = await fetchJson(url);
  assertTikTokApiSuccess(data, 'user/detail');
} catch (e) {
  if (e.message.startsWith('AUTH_REQUIRED')) await refreshSession();
  throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

const loggedIn = await page.evaluate(() => document.cookie.includes('sessionid'));
if (!loggedIn) throw new Error('AUTH_REQUIRED: log in to tiktok.com first');

Type guard

function isAuthRequiredPayload(data) {
  const code = Number(data?.status_code ?? data?.statusCode ?? 0);
  const msg = String(data?.status_msg ?? data?.statusMsg ?? data?.message ?? data?.msg ?? '');
  return code === 8 || /auth|captcha|login|permission|unauthori[sz]ed|forbidden/i.test(msg);
}

Try / catch

try { assertTikTokApiSuccess(data, label); } catch (e) {
  if (e.message.startsWith('AUTH_REQUIRED')) { await refreshSession(); return retry(label); }
  throw e;
}

Prevention

When it happens

Trigger: A TikTok API response arrived with a non-zero status_code equal to 8, or status_msg/statusMsg/message/msg matched /auth|captcha|login|permission|unauthorized|forbidden/i.

Common situations: Cookies expired mid-scrape so the API returns an auth error code; TikTok served a captcha challenge; the account lacks permission for the requested data; API schema change renamed status fields so a real success is misread — though that yields the generic branch instead.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/75ff39ba4dbf399e. Report an issue: GitHub.