jackwener/OpenCLI · error · CommandExecutionError

hf paper returned HTTP ${resp.status}

Error message

hf paper returned HTTP ${resp.status}

What it means

CommandExecutionError(`hf paper returned HTTP ${resp.status}`) — the generic catch-all for any non-OK response from HF's /api/papers that is not 404 or 429 (e.g. 500, 502, 503, 403). It surfaces the raw status code because HF did not return a usable paper payload and the failure mode doesn't match a more specific branch.

Source

Thrown at clis/hf/paper.js:51

        const url = `${endpoint}/api/papers/${encodeURIComponent(raw)}`;
        let resp;
        try {
            resp = await fetch(url, { headers: { accept: 'application/json' } });
        }
        catch (err) {
            throw new CommandExecutionError(`hf paper request failed: ${err?.message ?? err}`);
        }
        if (resp.status === 404) {
            throw new EmptyResultError('hf paper', `Hugging Face has no paper page for "${raw}".`);
        }
        if (resp.status === 429) {
            throw new CommandExecutionError(
                'hf paper returned HTTP 429 (rate limited)',
                'Hugging Face throttles unauthenticated traffic; wait a few seconds and retry.',
            );
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`hf paper returned HTTP ${resp.status}`);
        }
        let body;
        try {
            body = await resp.json();
        }
        catch (err) {
            throw new CommandExecutionError(`hf paper returned malformed JSON: ${err?.message ?? err}`);
        }
        if (!body || typeof body !== 'object' || !body.id) {
            throw new EmptyResultError('hf paper', `Hugging Face returned no paper data for "${raw}".`);
        }
        const authors = Array.isArray(body.authors)
            ? body.authors.map((a) => (typeof a === 'object' && a ? (a.name || a.fullname || '') : String(a))).filter(Boolean)
            : [];
        const aiKeywords = Array.isArray(body.ai_keywords) ? body.ai_keywords.join(', ') : '';
        return [{
            id: String(body.id),
            title: String(body.title ?? ''),

View on GitHub (pinned to 49907e53dc)

Solutions

1. Read the status code in the message: 5xx means retry later after an outage window; 403 means a proxy/WAF is blocking you.
2. Check https://status.huggingface.co for an ongoing HF incident before debugging your own setup.
3. Retry with backoff for transient 502/503/504 responses.
4. Test the same URL with curl -i to see full headers and any proxy-injected error body.
5. If HF_ENDPOINT points at a mirror, verify the mirror actually proxies /api/papers correctly or revert to the default endpoint.

Example fix

// before (debugging blind)
opencli hf paper 1706.03762   // hf paper returned HTTP 503
// after
unset HF_ENDPOINT && curl -sS -o /dev/null -w '%{http_code}' https://huggingface.co/api/papers/1706.03762  # confirm endpoint health, then retry

// health-check the endpoint before running
const probe = await fetch('https://huggingface.co/api/papers/1706.03762');
if (!probe.ok && probe.status !== 404) {
  throw new Error(`HF endpoint unhealthy (HTTP ${probe.status}) — check status.huggingface.co`);
}

function isHttpError(e) {
  const m = /hf paper returned HTTP (\d+)/.exec(String(e?.message));
  return m ? { httpStatus: Number(m[1]) } : null;
}

try {
  await run(['opencli', 'hf paper', id]);
} catch (e) {
  const m = /hf paper returned HTTP (\d+)/.exec(String(e.message));
  if (m) {
    const status = Number(m[1]);
    if (status >= 500) { /* retry later / check status.huggingface.co */ }
    else if (status === 403) { /* fix proxy/WAF egress */ }
    else throw e;
  } else throw e;
}

When it happens

Trigger: GET /api/papers/<id> returns any status outside 2xx, other than 404/429: HF server error (5xx), an edge/CDN 502/503 during an outage, or a 403 from a WAF/proxy blocking the request.

Common situations: Hugging Face incident or maintenance window returning 5xx; CDN hiccups; corporate firewall/WAF rewriting the response to 403; misconfigured HF_ENDPOINT pointing at a service that returns unexpected statuses.

Related errors

• coingecko categories returned HTTP ${resp.status}
• coingecko coin failed: HTTP ${resp.status}
• coingecko trending failed: HTTP ${resp.status}
• ${label} returned HTTP ${resp.status}
• ${label} returned HTTP ${resp.status}

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