jackwener/OpenCLI · error · CommandExecutionError

archive search failed: HTTP ${resp.status}

Error message

archive search failed: HTTP ${resp.status}

What it means

This CommandExecutionError is thrown when the archive.org advancedsearch endpoint returns an HTTP response whose status is not ok (resp.ok false, i.e. outside 2xx). The status code is embedded in the message. Unlike error 286, the request completed at the network level — the server answered with an error status.

Source

Thrown at clis/archive/search.js:76

        url.searchParams.set('rows', String(limit));
        url.searchParams.set('sort[]', `${sort} desc`);
        for (const fl of ['identifier', 'title', 'creator', 'date', 'mediatype', 'downloads']) {
            url.searchParams.append('fl[]', fl);
        }

        let resp;
        try {
            resp = await fetch(url, {
                headers: {
                    'Accept': 'application/json',
                    'User-Agent': 'opencli/1.0 (+https://github.com/jackwener/opencli)',
                },
            });
        } catch (error) {
            throw new CommandExecutionError(`archive search request failed: ${error?.message || error}`);
        }
        if (!resp.ok) {
            throw new CommandExecutionError(`archive search failed: HTTP ${resp.status}`);
        }
        let data;
        try {
            data = await resp.json();
        } catch (error) {
            throw new CommandExecutionError(`archive search returned malformed JSON: ${error?.message || error}`);
        }

        const docs = data?.response?.docs;
        if (!Array.isArray(docs)) {
            throw new CommandExecutionError('archive search returned malformed payload: response.docs must be an array');
        }
        if (docs.length === 0) {
            throw new EmptyResultError('archive search', `No items match "${query}" on archive.org.`);
        }

        return docs.slice(0, limit).map((d, i) => {
            const id = String(d.identifier ?? '');

View on GitHub (pinned to 49907e53dc)

Solutions

1. Read the HTTP status in the message: retry with backoff for 429/5xx, do not retry 4xx
2. Slow down or add jitter between successive searches to avoid rate limiting
3. Check https://status.archive.org for ongoing incidents on 5xx
4. Simplify or quote the query if a 400 suggests the server rejected the query syntax

Example fix

// before
for (const q of queries) rows.push(await run(['archive', 'search', q]));
// after
for (const q of queries) {
    try {
        rows.push(await run(['archive', 'search', q]));
    } catch (err) {
        if (/HTTP (429|5\d\d)/.test(String(err?.message))) {
            await new Promise(r => setTimeout(r, 2000));
            rows.push(await run(['archive', 'search', q]));
        } else { throw err; }
    }
}

// nothing to validate pre-call; status is server-side
// throttle proactively:
await sleep(1000); // keep request rate under archive.org limits

null

try {
    rows = await run(['archive', 'search', query]);
} catch (err) {
    const m = /HTTP (\d{3})/.exec(String(err?.message));
    if (err instanceof CommandExecutionError && m && ['429','500','502','503','504'].includes(m[1])) {
        await new Promise(r => setTimeout(r, 2000 * Number(m[1] === '429')));
        rows = await run(['archive', 'search', query]);
    } else { throw err; }
}

When it happens

Trigger: Calling `opencli archive search ...` and archive.org returns 403 (rate limiting/blocked UA/IP), 429 (too many requests), 500/503 (server-side incident), or 502/504 from its edge.

Common situations: Hammering the API in a loop and getting rate-limited (429); archive.org maintenance windows returning 503; datacenter IPs being blocked with 403; malformed query syntax causing server-side 400s.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• archive item returned malformed payload: files must be an ar
• archive search returned malformed payload: response.docs mus
• hf spaces failed: HTTP ${resp.status}
• FETCH_ERROR
• workspace/create failed: ret=${resp.ret} errmsg=${resp.errms

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