{"record":{"id":"396c51cbdb0bad09","repo":"jackwener/OpenCLI","slug":"hf-paper-returned-http-resp-status","errorCode":null,"errorMessage":"hf paper returned HTTP ${resp.status}","messagePattern":"hf paper returned HTTP (.+?)","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/hf/paper.js","lineNumber":51,"sourceCode":"        const url = `${endpoint}/api/papers/${encodeURIComponent(raw)}`;\n        let resp;\n        try {\n            resp = await fetch(url, { headers: { accept: 'application/json' } });\n        }\n        catch (err) {\n            throw new CommandExecutionError(`hf paper request failed: ${err?.message ?? err}`);\n        }\n        if (resp.status === 404) {\n            throw new EmptyResultError('hf paper', `Hugging Face has no paper page for \"${raw}\".`);\n        }\n        if (resp.status === 429) {\n            throw new CommandExecutionError(\n                'hf paper returned HTTP 429 (rate limited)',\n                'Hugging Face throttles unauthenticated traffic; wait a few seconds and retry.',\n            );\n        }\n        if (!resp.ok) {\n            throw new CommandExecutionError(`hf paper returned HTTP ${resp.status}`);\n        }\n        let body;\n        try {\n            body = await resp.json();\n        }\n        catch (err) {\n            throw new CommandExecutionError(`hf paper returned malformed JSON: ${err?.message ?? err}`);\n        }\n        if (!body || typeof body !== 'object' || !body.id) {\n            throw new EmptyResultError('hf paper', `Hugging Face returned no paper data for \"${raw}\".`);\n        }\n        const authors = Array.isArray(body.authors)\n            ? body.authors.map((a) => (typeof a === 'object' && a ? (a.name || a.fullname || '') : String(a))).filter(Boolean)\n            : [];\n        const aiKeywords = Array.isArray(body.ai_keywords) ? body.ai_keywords.join(', ') : '';\n        return [{\n            id: String(body.id),\n            title: String(body.title ?? ''),","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/hf/paper.js#L33-L69","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the status code in the message: 5xx means retry later after an outage window; 403 means a proxy/WAF is blocking you.","Check https://status.huggingface.co for an ongoing HF incident before debugging your own setup.","Retry with backoff for transient 502/503/504 responses.","Test the same URL with curl -i to see full headers and any proxy-injected error body.","If HF_ENDPOINT points at a mirror, verify the mirror actually proxies /api/papers correctly or revert to the default endpoint."],"exampleFix":"// before (debugging blind)\nopencli hf paper 1706.03762   // hf paper returned HTTP 503\n// after\nunset HF_ENDPOINT && curl -sS -o /dev/null -w '%{http_code}' https://huggingface.co/api/papers/1706.03762  # confirm endpoint health, then retry","handlingStrategy":"try-catch","validationCode":"// health-check the endpoint before running\nconst probe = await fetch('https://huggingface.co/api/papers/1706.03762');\nif (!probe.ok && probe.status !== 404) {\n  throw new Error(`HF endpoint unhealthy (HTTP ${probe.status}) — check status.huggingface.co`);\n}","typeGuard":"function isHttpError(e) {\n  const m = /hf paper returned HTTP (\\d+)/.exec(String(e?.message));\n  return m ? { httpStatus: Number(m[1]) } : null;\n}","tryCatchPattern":"try {\n  await run(['opencli', 'hf paper', id]);\n} catch (e) {\n  const m = /hf paper returned HTTP (\\d+)/.exec(String(e.message));\n  if (m) {\n    const status = Number(m[1]);\n    if (status >= 500) { /* retry later / check status.huggingface.co */ }\n    else if (status === 403) { /* fix proxy/WAF egress */ }\n    else throw e;\n  } else throw e;\n}","preventionTips":["Check https://status.huggingface.co before large batch runs.","Retry with backoff on 5xx statuses — they are usually transient.","Verify HF_ENDPOINT mirrors actually proxy /api/papers.","Confirm corporate proxies/WAFs are not rewriting responses.","Test the exact URL with curl -i to see full headers when debugging."],"tags":["http-error","huggingface","cli","server-error"],"backgroundTag":"unexpected-http-status","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}