jackwener/OpenCLI · error · CommandExecutionError

hf spaces failed: HTTP ${resp.status}

Error message

hf spaces failed: HTTP ${resp.status}

What it means

The Hugging Face Spaces API returned an HTTP status outside 2xx (other than the specially handled 429). The library surfaces the raw status code because the response body was not inspected, indicating the request was rejected or the endpoint changed.

Source

Thrown at clis/hf/spaces.js:71

        if (sdk) url.searchParams.set('sdk', sdk);

        let resp;
        try {
            resp = await fetch(url, {
                headers: { Accept: 'application/json', 'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)' },
            });
        }
        catch (err) {
            throw new CommandExecutionError(`hf spaces request failed: ${err?.message ?? err}`);
        }
        if (resp.status === 429) {
            throw new CommandExecutionError(
                'hf spaces returned HTTP 429 (rate limited)',
                'Hugging Face throttles unauthenticated traffic; wait a few seconds and retry.',
            );
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`hf spaces failed: HTTP ${resp.status}`);
        }
        let data;
        try {
            data = await resp.json();
        }
        catch (err) {
            throw new CommandExecutionError(`hf spaces returned malformed JSON: ${err?.message ?? err}`);
        }
        const list = Array.isArray(data) ? data : [];
        if (!list.length) {
            throw new EmptyResultError('hf spaces', 'No matching spaces on huggingface.co.');
        }
        return list.slice(0, limit).map((s, i) => {
            const id = String(s.id ?? s._id ?? '');
            const slash = id.indexOf('/');
            const author = String(s.author ?? (slash > 0 ? id.slice(0, slash) : ''));
            const tags = Array.isArray(s.tags) ? s.tags.filter((t) => !String(t).startsWith('license:')).slice(0, 10).join(', ') : '';
            return {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Check https://huggingface.co/docs/api-inference or the /api/spaces endpoint status directly with curl
2. Verify any query filters/parameters are valid for the current HF API
3. Retry later on 5xx (HF server-side issue)
4. Check whether a proxy is injecting 4xx/5xx responses

Example fix

// before: no diagnostics
throw new CommandExecutionError(`hf spaces failed: HTTP ${resp.status}`);
// after
const body = await resp.text().catch(() => '');
throw new CommandExecutionError(`hf spaces failed: HTTP ${resp.status}: ${body.slice(0, 200)}`);

const probe = await fetch('https://huggingface.co/api/spaces?limit=1');
if (!probe.ok) console.warn(`HF API unhealthy: HTTP ${probe.status}`);

try {
  await hfSpaces(query);
} catch (e) {
  const m = /HTTP (\d{3})/.exec(e.message);
  if (m) {
    const status = Number(m[1]);
    if (status >= 500) return retryLater();      // HF-side issue
    if (status === 403 || status === 401) return checkAuthProxy(); // client env
  }
  throw e;
}

When it happens

Trigger: GET /api/spaces returns 404 (endpoint moved), 401/403 (restricted resource or blocked client), 5xx (HF server-side error), or any non-ok status while resp.status !== 429.

Common situations: HF API breaking changes or maintenance windows; corporate proxies returning 403/502 with their own error pages; malformed query parameters causing 400 responses.

Related errors

• FETCH_ERROR
• archive search failed: HTTP ${resp.status}
• hf datasets failed: HTTP ${resp.status}
• hf models failed: HTTP ${resp.status}
• workspace/create failed: ret=${resp.ret} errmsg=${resp.errms

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