feat(docs): Add Ask AI error documentation (#2726)

* feat(docs): Add Ask AI error documentation

* feat(askai): Render AI stream error messages as Markdown to allow for links

Author: 8bittitan

packages/docsearch-css/src/modal.css

@@ -928,7 +928,7 @@ assistive tech users */
 .DocSearch-AskAiScreen-Error {
   padding: var(--docsearch-spacing);
   display: flex;
-  align-items: center;
+  align-items: baseline;
   padding: 1em;
   gap: 8px;
   color: var(--docsearch-error-color);
@@ -941,12 +941,17 @@ assistive tech users */
 .DocSearch-AskAiScreen-Error svg {
   width: 16px;
   height: 16px;
+  flex-shrink: 0;
 }
 
 .DocSearch-AskAiScreen-Error p {
   margin: 0;
 }
 
+.DocSearch-AskAiScreen-Error .DocSearch-Markdown-Content {
+  color: var(--docsearch-error-color);
+}
+
 .DocSearch-AskAiScreen-FeedbackText {
   font-size: 0.7em;
   font-weight: 400;

packages/docsearch-react/src/AskAiScreen.tsx

@@ -112,7 +112,12 @@ function AskAiExchangeCard({
             {loadingStatus === 'error' && askAiStreamError && isLastExchange && (
               <div className="DocSearch-AskAiScreen-MessageContent DocSearch-AskAiScreen-Error">
                 <AlertIcon />
-                <p>{askAiStreamError.message}</p>
+                <MemoizedMarkdown
+                  content={askAiStreamError.message}
+                  copyButtonText=""
+                  copyButtonCopiedText=""
+                  isStreaming={false}
+                />
               </div>
             )}
             {loadingStatus === 'submitted' && isLastExchange && (

packages/website/docs/v4/askai-api.mdx

@@ -114,15 +114,15 @@ Search parameters allow you to control how Ask AI searches your index:
   "id": "conversation-1",
   "messages": [
     {
-      "role": "user", 
+      "role": "user",
       "content": "How do I configure the API?",
       "id": "msg-1"
     }
   ],
   "searchParameters": {
     "facetFilters": [
       "language:en",
-      "version:latest", 
+      "version:latest",
       "type:content"
     ]
   }
@@ -158,7 +158,7 @@ This example filters to:
 - **Multiple tags**: `[["tag:api", "tag:tutorial"]]` for OR logic
 - **Categories with fallbacks**: `[["category:advanced", "category:intermediate"]]`
 
-**Response:** 
+**Response:**
 - **Content-Type:** `text/event-stream`
 - **Format:** Server-sent events with incremental AI response chunks
 - **Benefits:** Real-time response display, better user experience, lower perceived latency
@@ -173,7 +173,7 @@ const decoder = new TextDecoder();
 while (true) {
   const { done, value } = await reader.read();
   if (done) break;
-  
+
   const chunk = decoder.decode(value);
   // Display chunk immediately in your UI
   console.log('Received chunk:', chunk);
@@ -250,7 +250,7 @@ class AskAIChat {
 
   async sendMessage(conversationId, messages, searchParameters = {}) {
     const token = await this.getToken();
-    
+
     const response = await fetch(`${this.baseUrl}/chat`, {
       method: 'POST',
       headers: {
@@ -277,12 +277,12 @@ class AskAIChat {
       async *[Symbol.asyncIterator]() {
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
-        
+
         try {
           while (true) {
             const { done, value } = await reader.read();
             if (done) break;
-            
+
             // Decode and yield each chunk as it arrives
             const chunk = decoder.decode(value, { stream: true });
             if (chunk.trim()) {
@@ -298,7 +298,7 @@ class AskAIChat {
 
   async submitFeedback(messageId, thumbs) {
     const token = await this.getToken();
-    
+
     const response = await fetch(`${this.baseUrl}/chat/feedback`, {
       method: 'POST',
       headers: {
@@ -428,15 +428,15 @@ function AskAIChat({ appId, apiKey, indexName, assistantId }) {
       while (true) {
         const { done, value } = await reader.read();
         if (done) break;
-        
+
         // Decode chunk and add to message
         const chunk = decoder.decode(value, { stream: true });
         if (chunk.trim()) {
           assistantMessage += chunk;
-          
+
           // Update UI with streaming content immediately
-          setMessages(prev => prev.map(msg => 
-            msg.id === assistantMessageId 
+          setMessages(prev => prev.map(msg =>
+            msg.id === assistantMessageId
               ? { ...msg, content: assistantMessage }
               : msg
           ));
@@ -470,7 +470,7 @@ function AskAIChat({ appId, apiKey, indexName, assistantId }) {
       <div className="messages">
         {messages.map((message) => (
           <div key={message.id} className={`message ${message.role}`}>
-            <strong>{message.role}:</strong> 
+            <strong>{message.role}:</strong>
             <span className={isStreaming && message.role === 'assistant' && message === messages[messages.length - 1] ? 'streaming' : ''}>
               {message.content}
               {isStreaming && message.role === 'assistant' && message === messages[messages.length - 1] && (
@@ -480,20 +480,20 @@ function AskAIChat({ appId, apiKey, indexName, assistantId }) {
           </div>
         ))}
       </div>
-      
+
       <form onSubmit={(e) => {
         e.preventDefault();
         if (isLoading) return;
-        
+
         const input = e.target.elements.message;
         if (input.value.trim()) {
           sendMessage(input.value);
           input.value = '';
         }
       }}>
-        <input 
-          name="message" 
-          type="text" 
+        <input
+          name="message"
+          type="text"
           placeholder="Ask a question..."
           disabled={isLoading}
         />
@@ -594,7 +594,7 @@ async function getToken(assistantId: string, origin: string) {
       'Origin': origin,
     },
   });
-  
+
   const tokenData = await tokenRes.json();
   if (!tokenData.success) {
     throw new Error(tokenData.message || 'Failed to get token');
@@ -607,7 +607,7 @@ export default async function handler(req: Request) {
     const body = await req.json();
     const assistantId = process.env.ALGOLIA_ASSISTANT_ID!;
     const origin = req.headers.get('origin') || '';
-    
+
     // Fetch a new token before each chat call
     const token = await getToken(assistantId, origin);
 
@@ -637,7 +637,7 @@ export default async function handler(req: Request) {
   } catch (error) {
     console.error('Chat API error:', error);
     return new Response(
-      JSON.stringify({ error: 'Internal server error' }), 
+      JSON.stringify({ error: 'Internal server error' }),
       { status: 500, headers: { 'Content-Type': 'application/json' } }
     );
   }
@@ -721,6 +721,8 @@ Common error scenarios:
 - **Rate limiting**: Too many requests
 - **Invalid index**: Index name doesn't exist or isn't accessible
 
+> Please view our full [Error Reference](/docs/v4/askai-errors.mdx) for more detailed information
+
 ---
 
 ## Best Practices
@@ -731,4 +733,4 @@ Common error scenarios:
 4. **Feedback**: Implement thumbs up/down for continuous improvement
 5. **CORS**: Ensure your domain is whitelisted in your Ask AI configuration
 
-For more information, see the [Ask AI documentation](/docs/v4/askai.mdx). 
+For more information, see the [Ask AI documentation](/docs/v4/askai.mdx).

packages/website/docs/v4/askai-errors.mdx

@@ -0,0 +1,65 @@
+---
+title: Ask AI Errors Reference
+---
+
+This is a reference to error codes and their definitions that can be returned from the Ask AI Chat.
+
+## General API errors
+
+---
+
+### UNAUTHORIZED
+
+There was an issue validating the auth token for the request.
+
+### FORBIDDEN
+
+Access to a resources is not available or not allowed for the requester.
+
+> **Solution:** Make sure that your domain is [white listed](/docs/v4/askai-whitelisted-domains) and that you are using the correct `assistantId`.
+
+### BAD_INPUT
+
+The request included data that could either not be used to find a resource, or the data was malformed.
+
+### TOO_MANY_ATTEMPTS
+
+There have been too many requets made within a designated window. The requests are being rate limitted.
+
+> **Solution:** Wait a bit of time for the rate limit window to pass and then try again.
+
+## Ask AI chat errors
+
+---
+
+### AI_STREAM_ERROR
+
+A general case error that occured while from communicating with the upstream provider. This could include stream procesing issues, data corruption, issues with the provider itself and so on.
+
+### AI_API_CALL
+
+There was an issue specifically with communicating with the upstream provider.
+
+> **Solution:** Check the provider's API status pages(s) to see if they are experiencing any ongoing issues.
+
+### AI_INVALID_API_KEY
+
+The upstream provider reported that there was an issue with the supplied API key.
+
+> **Solution:** Make sure to double check that you are using the correct API key for your assistant; and that it has the correct permissions.
+
+### AI_INSUFFICIENT_BALANCE
+
+The upstream provider could not process the chat request to due a billing issue.
+
+> **Solution:** You will need to log into to your provider's dashboard to remedy this issue.
+
+### AI_NO_TOOL
+
+Ask AI could not call a specific tool.
+
+> **Solution:** Be sure to not ask for any specific tool calls within your custom prompt. Ask AI has specific tools it uses to give the best results.
+
+### AI_RETRY
+
+There were too many failed attempts at communicating with the upstream provider. This could be an issue on the provider's end, an issue with the supplied API key or an underlying network issue causing these retries.

packages/website/sidebars.js

@@ -31,6 +31,7 @@ export default {
         'v4/askai-whitelisted-domains',
         'v4/askai-models',
         'v4/askai-markdown-indexing',
+        'v4/askai-errors',
       ],
     },
     {