What causes "Brave Search API server error: {error_message}" in zylon-ai/private-gpt?

Retry with backoff — 5xx are usually transient.

zylon-ai/private-gpt · error · Exception

Brave Search API server error: {error_message}

Error message

Brave Search API server error: {error_message}

What it means

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.

Source

Thrown at private_gpt/components/web/web_search/providers/brave.py:246

            raise QuotaConsumed(
                "Brave Search API quota exhausted (x-ratelimit-remaining=0)"
            )

        status_code = response.status
        if status_code < 400:
            return

        error = response_data.get("error", "Unknown error")
        error_message = self._extract_error_message(error)
        if status_code == 429:
            logger.debug(f"Brave Search API rate limit exceeded: {error_message}")
            raise RateLimitExceeded(
                f"Brave Search API rate limit exceeded: {error_message}"
            )
        elif status_code == 400:
            raise ValueError(f"Brave Search API invalid token ({error_message})")
        elif status_code >= 500:
            raise Exception(f"Brave Search API server error: {error_message}")
        else:
            raise Exception(f"Brave Search API error ({status_code}): {error_message}")

    def _build_request_params(
        self,
        query: str,
        num_links: int,
        offset: int,
        result_filter: str,
        safesearch: bool,
        freshness: str | None,
        spellcheck: bool,
        language: str | None,
    ) -> dict[str, Any]:
        params = {
            "q": query.strip(),
            "count": num_links,
            "offset": offset,

View on GitHub (pinned to 4a030776a3)

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.

Example fix

# before
results = await web_search.search(q)

# after
try:
    results = await web_search.search(q)
except Exception as e:
    if 'server error' not in str(e):
        raise
    results = []  # degrade gracefully, log for retry

Defensive patterns

Strategy: retry

Type guard

def is_brave_server_error(exc: BaseException) -> bool:
    return isinstance(exc, Exception) and 'Brave Search API server error' in str(exc)

Try / catch

try:
    results = await provider.make_query(q, num_links)
except Exception as e:
    if 'Brave Search API server error' not in str(e):
        raise
    await asyncio.sleep(2)
    results = await provider.make_query(q, num_links)  # 5xx are transient

Prevention

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.

When it happens

Trigger: Brave infrastructure incidents/outages; transient 502/503 from their gateways; occasional 500s on unusual query parameters that trip a backend bug.

Common situations: Production searches failing during a Brave outage (check status pages); sporadic single failures under steady traffic that succeed on retry.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/4358fceed300f6d6. Report an issue: GitHub.