deepsearch/api: remove 'failed' conversation status (#1457)

This status doesn't exist. After poking at it for a while in
sourcegraph/sourcegraph#7964 I've decided the
change is a bit too pervasive (since we store external API shape
directly into DB), and it's probably better to just fix the docs.

Sadly, it looks like there's no published schema for this, so I also
added what the error behaviour is supposed to be.

Part of https://linear.app/sourcegraph/issue/CU-1495/api-housekeeping

Author: bobheadxi

docs/deep-search/api.mdx

@@ -257,12 +257,27 @@ curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?filter_read_token
 
 -   `id` - Unique question identifier
 -   `question` - The original question text
--   `status` - Processing status: `pending`, `processing`, `completed`, `failed`
+-   `status` - Processing status: `pending`, `processing`, `completed`
+-   `error` - Error details if the question processing encountered an issue
 -   `title` - Generated title for the question
 -   `answer` - The AI-generated answer (when completed)
 -   `sources` - Array of sources used to generate the answer
 -   `suggested_followups` - Suggested follow-up questions
 
+If a question fails to process, the `status` will be `completed` and the `error` field will be populated, for example:
+
+```json
+{
+  "status": "completed",
+  "error": {
+    "title": "Token limit reached",
+    "kind": "TokenLimitExceeded",
+    "message": "The search exceeded the maximum token limit...",
+    "details": "Additional context about the error"
+  }
+}
+```
+
 ## Error handling
 
 The API returns standard HTTP status codes with descriptive error messages: