{"record":{"id":"4358fceed300f6d6","repo":"zylon-ai/private-gpt","slug":"brave-search-api-server-error-error-message","errorCode":null,"errorMessage":"Brave Search API server error: {error_message}","messagePattern":"Brave Search API server error: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"private_gpt/components/web/web_search/providers/brave.py","lineNumber":246,"sourceCode":"            raise QuotaConsumed(\n                \"Brave Search API quota exhausted (x-ratelimit-remaining=0)\"\n            )\n\n        status_code = response.status\n        if status_code < 400:\n            return\n\n        error = response_data.get(\"error\", \"Unknown error\")\n        error_message = self._extract_error_message(error)\n        if status_code == 429:\n            logger.debug(f\"Brave Search API rate limit exceeded: {error_message}\")\n            raise RateLimitExceeded(\n                f\"Brave Search API rate limit exceeded: {error_message}\"\n            )\n        elif status_code == 400:\n            raise ValueError(f\"Brave Search API invalid token ({error_message})\")\n        elif status_code >= 500:\n            raise Exception(f\"Brave Search API server error: {error_message}\")\n        else:\n            raise Exception(f\"Brave Search API error ({status_code}): {error_message}\")\n\n    def _build_request_params(\n        self,\n        query: str,\n        num_links: int,\n        offset: int,\n        result_filter: str,\n        safesearch: bool,\n        freshness: str | None,\n        spellcheck: bool,\n        language: str | None,\n    ) -> dict[str, Any]:\n        params = {\n            \"q\": query.strip(),\n            \"count\": num_links,\n            \"offset\": offset,","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/web/web_search/providers/brave.py#L228-L264","documentation":"Generic Exception raised when Brave Search responds with HTTP 5xx. The provider deliberately uses a bare Exception for upstream server errors, including the error message extracted from the response body. These are Brave-side failures: the request was valid but the API or an internal dependency failed.","triggerScenarios":"Brave infrastructure incidents/outages; transient 502/503 from their gateways; occasional 500s on unusual query parameters that trip a backend bug.","commonSituations":"Production searches failing during a Brave outage (check status pages); sporadic single failures under steady traffic that succeed on retry.","solutions":["Retry with backoff — 5xx are usually transient.","Check Brave status/community channels for ongoing incidents if failures persist.","Circuit-break search in your app (fall back to index-only answers) while Brave is down.","If a specific query reliably 500s, simplify the parameters (freshness/language filters) and report to Brave."],"exampleFix":"# before\nresults = await web_search.search(q)\n\n# after\ntry:\n    results = await web_search.search(q)\nexcept Exception as e:\n    if 'server error' not in str(e):\n        raise\n    results = []  # degrade gracefully, log for retry","handlingStrategy":"retry","validationCode":null,"typeGuard":"def is_brave_server_error(exc: BaseException) -> bool:\n    return isinstance(exc, Exception) and 'Brave Search API server error' in str(exc)","tryCatchPattern":"try:\n    results = await provider.make_query(q, num_links)\nexcept Exception as e:\n    if 'Brave Search API server error' not in str(e):\n        raise\n    await asyncio.sleep(2)\n    results = await provider.make_query(q, num_links)  # 5xx are transient","preventionTips":["Retry 5xx with jittered exponential backoff, capped attempts.","Degrade to index-only answers when Brave is unavailable instead of failing the request.","Track 5xx rate separately from 4xx to distinguish upstream incidents."],"tags":["brave","http-5xx","transient","retry"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}