What causes "HF API error: ${res.status} ${res.statusText}" in jackwener/OpenCLI?

Retry later if status is 5xx (HF-side incident)

jackwener/OpenCLI · error · CliError

FETCH_ERROR

FETCH_ERROR

Error message

HF API error: ${res.status} ${res.statusText}

What it means

A CliError with code FETCH_ERROR thrown when the HF papers endpoint (/api/papers?period=weekly|monthly) returns a non-2xx status. The status code and statusText are surfaced so the caller knows whether it's a client or server problem.

Source

Thrown at clis/hf/top.js:66

            return kwargs._footerDate;
        if (kwargs.period === 'monthly')
            return getMonthRange();
        if (kwargs.period === 'weekly')
            return getWeekRange();
        return kwargs.date ?? new Date().toISOString().slice(0, 10);
    },
    func: async (kwargs) => {
        const period = String(kwargs.period ?? 'daily');
        const all = Boolean(kwargs.all);
        const endpoint = process.env.HF_ENDPOINT?.replace(/\/+$/, '') || 'https://huggingface.co';
        if (period === 'weekly' || period === 'monthly') {
            if (kwargs.date) {
                throw new CliError('INVALID_ARG', `--date is not supported for ${period} period`, `Omit --date when using --period ${period}`);
            }
            const url = `${endpoint}/api/papers?period=${period}`;
            const res = await fetch(url);
            if (!res.ok)
                throw new CliError('FETCH_ERROR', `HF API error: ${res.status} ${res.statusText}`, 'Check HF_ENDPOINT or try again later');
            const body = await res.json();
            if (!Array.isArray(body))
                throw new CliError('FETCH_ERROR', 'Unexpected HF API response', 'Check endpoint');
            const data = body;
            const dates = data.map((d) => d.publishedAt).filter(Boolean).sort();
            if (dates.length > 0) {
                if (period === 'monthly') {
                    const d = new Date(dates[0]);
                    kwargs._footerDate = `${MONTH_ABBR[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
                }
                else {
                    const start = new Date(dates[0]);
                    const end = new Date(dates[dates.length - 1]);
                    const sm = MONTH_ABBR[start.getUTCMonth()];
                    const em = MONTH_ABBR[end.getUTCMonth()];
                    const sd = start.getUTCDate();
                    const ed = end.getUTCDate();
                    kwargs._footerDate = sm === em ? `${sm} ${sd}-${ed}` : `${sm} ${sd}-${em} ${ed}`;

View on GitHub (pinned to 49907e53dc)

Solutions

Retry later if status is 5xx (HF-side incident)
Check HF_ENDPOINT — unset it or set it to https://huggingface.co
Test the URL directly: curl "$HF_ENDPOINT/api/papers?period=weekly"
Fix proxy/firewall blocking if status is 403/502

Example fix

// before
export HF_ENDPOINT=https://mirror.example.com  // doesn't implement /api/papers
// after
unset HF_ENDPOINT  # or export HF_ENDPOINT=https://huggingface.co

Defensive patterns

Strategy: retry

Validate before calling

// verify endpoint health and configuration first
const ep = (process.env.HF_ENDPOINT || 'https://huggingface.co').replace(/\/+$/, '');
const health = await fetch(`${ep}/api/papers?period=weekly`).then(r => r.ok).catch(() => false);
if (!health) console.warn(`HF papers endpoint not reachable at ${ep}`);

Try / catch

async function fetchPapers(period, tries = 3) {
  for (let i = 0; ; i++) {
    try { return await run(['hf', 'top', '--period', period]); }
    catch (e) {
      const m = /HTTP (\d{3})/.exec(String(e.message ?? e));
      if (!m || Number(m[1]) < 500 || i >= tries - 1) throw e;
      await new Promise(r => setTimeout(r, 2 ** i * 1000));
    }
  }
}

Prevention

Only override HF_ENDPOINT with a mirror that actually implements /api/papers
Include scheme in HF_ENDPOINT (https://...)
Retry with backoff on 5xx; treat 4xx as a config problem
Probe the endpoint with curl before scheduled runs

When it happens

Trigger: fetch to ${HF_ENDPOINT}/api/papers?period=weekly|monthly returns 4xx/5xx: HF outage, invalid HF_ENDPOINT override, rate limiting, or API changes.

Common situations: HF_ENDPOINT misconfigured to a mirror/proxy that doesn't implement /api/papers; HF API downtime; corporate proxy returning 403; typos in the env var value (e.g. missing scheme).

Related errors

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