From 312a5995f7b6d198d9706baac7050ba442cebf22 Mon Sep 17 00:00:00 2001
From: DrMelone <27028174+Classic298@users.noreply.github.com>
Date: Tue, 30 Dec 2025 13:15:19 +0100
Subject: [PATCH] brave

---
 docs/features/web-search/brave.md          | 22 ++++++++++++++++++++++
 docs/getting-started/env-configuration.mdx |  6 ++++++
 2 files changed, 28 insertions(+)

diff --git a/docs/features/web-search/brave.md b/docs/features/web-search/brave.md
index e4a9deaa0..e97a653c0 100644
--- a/docs/features/web-search/brave.md
+++ b/docs/features/web-search/brave.md
@@ -31,3 +31,25 @@ services:
       RAG_WEB_SEARCH_RESULT_COUNT: 3
       RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 1
 ```
+
+### Rate Limiting (Free Tier)
+
+Brave's free tier API enforces a strict limit of **1 request per second**. If your LLM generates multiple search queries (which is common), you may encounter HTTP 429 "Too Many Requests" errors.
+
+**Recommended configuration for free tier users:**
+
+- Set `RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 1` to ensure requests are processed sequentially rather than in parallel.
+
+**Automatic retry behavior:**
+
+Open WebUI automatically handles 429 rate limit responses from the Brave API. When a rate limit error is received, the system will:
+
+1. Wait 1 second (respecting Brave's rate limit)
+2. Retry the request once
+3. Only fail if the retry also returns an error
+
+This means that even if your connection is fast enough to send multiple sequential requests within a second, the automatic retry mechanism should recover gracefully without user intervention.
+
+:::tip
+If you are on Brave's paid tier with higher rate limits, you can increase `RAG_WEB_SEARCH_CONCURRENT_REQUESTS` for faster parallel searches.
+:::
diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx
index 93c44ca08..f248e8208 100644
--- a/docs/getting-started/env-configuration.mdx
+++ b/docs/getting-started/env-configuration.mdx
@@ -3085,6 +3085,12 @@ the search query. Example: `http://searxng.local/search?q=<query>`
 - Description: Sets the API key for the Brave Search API.
 - Persistence: This environment variable is a `PersistentConfig` variable.
 
+:::info
+
+Brave's free tier enforces a rate limit of 1 request per second. Open WebUI automatically retries requests that receive HTTP 429 rate limit errors after a 1-second delay. For free tier users, set `WEB_SEARCH_CONCURRENT_REQUESTS` to `1` to ensure sequential request processing. See the [Brave web search documentation](/features/web-search/brave) for more details.
+
+:::
+
 #### `KAGI_SEARCH_API_KEY`
 
 - Type: `str`