{"record":{"id":"cc3eda9bc4a5685d","repo":"GitbookIO/gitbook","slug":"search-request-failed-response-status","errorCode":null,"errorMessage":"Search request failed: ${response.status}","messagePattern":"Search request failed: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/gitbook/src/components/Search/useSearchResults.ts","lineNumber":348,"sourceCode":"    searchURL: string,\n    scope: SearchSiteContentScope,\n    query: string,\n    signal?: AbortSignal,\n    asEmbeddable?: boolean\n): Promise<OrderedComputedResult[]> {\n    const response = await fetch(searchURL, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({\n            asEmbeddable,\n            query,\n            scope,\n        }),\n        signal,\n    });\n\n    if (!response.ok) {\n        throw new Error(`Search request failed: ${response.status}`);\n    }\n\n    return response.json() as Promise<OrderedComputedResult[]>;\n}\n","sourceCodeStart":330,"sourceCodeEnd":353,"githubUrl":"https://github.com/GitbookIO/gitbook/blob/db67585ee243d063c459a855988f21612cea9c95/packages/gitbook/src/components/Search/useSearchResults.ts#L330-L353","documentation":"Thrown by fetchSearchResults in the GitBook search hook when the backend search endpoint returns a non-2xx HTTP status. The message embeds the raw status code (e.g. 401, 500, 503) from the response. It means the search request itself failed at the transport/HTTP level, not that zero results were found.","triggerScenarios":"Calling the site search API (the fetch wrapped with signal) and the server responding with response.ok === false — e.g. expired/invalid visitor API token (401), rate limiting (429), upstream GitBook API outage (5xx), or a bad scope/space ID in the request body.","commonSituations":"Local dev proxy dropping the Authorization/token header, expired visitor session tokens in long-lived tabs, GitBook API incidents, or passing an incorrect scope object when building the search request.","solutions":["Check the embedded HTTP status: 401/403 → refresh or re-provision the visitor/API token; 429 → back off and retry with the Retry-After hint; 5xx → retry later or report an incident","Inspect the request payload (query, scope) in the network tab and confirm the scope IDs match the current site structure","Verify the search endpoint URL and any proxy rewrites in your dev server are forwarding cookies/headers untouched","If using a custom deployment, confirm the API base URL and authentication middleware are configured for the search route"],"exampleFix":"// before\nconst results = await fetchSearchResults(query, scope, signal);\n\n// after\ntry {\n    const results = await fetchSearchResults(query, scope, signal);\n} catch (error) {\n    if (error instanceof Error && error.message.startsWith('Search request failed:')) {\n        const status = Number(error.message.split(': ')[1]);\n        if (status === 429 || status >= 500) {\n            // transient — surface a retry affordance instead of a hard failure\n            return [];\n        }\n    }\n    throw error;\n}","handlingStrategy":"try-catch","validationCode":"const statusOk = (s?: number) => s !== undefined && s >= 200 && s < 300;","typeGuard":"function isSearchRequestError(e: unknown): e is Error {\n    return e instanceof Error && e.message.startsWith('Search request failed:');\n}","tryCatchPattern":"try {\n    const results = await fetchSearchResults(query, scope, signal);\n} catch (error) {\n    if (isSearchRequestError(error)) {\n        const status = Number(error.message.split(': ')[1]);\n        if (status === 429 || status >= 500) return []; // transient: degrade gracefully\n    }\n    throw error;\n}","preventionTips":["Abort in-flight searches via the signal on input change to cut down raced requests","Monitor 4xx vs 5xx rates separately to distinguish config problems from outages","Retry only 429/5xx with exponential backoff; never retry 4xx auth errors"],"tags":["search","http-status","network","react-hooks"],"backgroundTag":"http-request-failed","analyzedSha":"db67585ee243d063c459a855988f21612cea9c95","analyzedAt":"2026-08-28T17:49:47.831Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}