improve error handling for overly long search queries

when users submit search queries exceeding turbopuffer's 1024 character limit for BM25 text search, the application now returns a 400 Bad Request with a helpful error message instead of a generic 500 Internal Server Error.

changes:
- add TurbopufferError enum to categorize different error types
- parse turbopuffer API error responses to detect query length violations
- return 400 status with user-friendly message for query length errors
- maintain 500 status for genuine server errors

this fix ensures users understand the limitation and can adjust their queries accordingly, without falsely suggesting a server-side problem.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

Cargo.lock

···
  "reqwest",
  "serde",
  "serde_json",
+ "thiserror 1.0.69",
  "tokio",
  "tracing",
 ]

Cargo.toml

···
 tokio = { version = "1", features = ["full"] }
 reqwest = { version = "0.12", features = ["json", "multipart"] }
 anyhow = "1.0"
+thiserror = "1.0"
 dotenv = "0.15"
 base64 = "0.22"
 actix-governor = "0.10.0"

src/search.rs

···
 
 use crate::config::Config;
 use crate::embedding::EmbeddingClient;
-use crate::turbopuffer::{QueryRequest, TurbopufferClient};
+use crate::turbopuffer::{QueryRequest, TurbopufferClient, TurbopufferError};
 use actix_web::{web, HttpRequest, HttpResponse, Result as ActixResult};
 use serde::{Deserialize, Serialize};
 use std::collections::hash_map::DefaultHasher;
···
                 query = &query_text,
                 top_k = search_top_k as i64
             );
-            actix_web::error::ErrorInternalServerError(format!(
-                "failed to query turbopuffer (BM25): {}",
-                e
-            ))
+
+            // return appropriate HTTP status based on error type
+            match e {
+                TurbopufferError::QueryTooLong { .. } => {
+                    actix_web::error::ErrorBadRequest(
+                        "search query is too long (max 1024 characters for text search). try a shorter query."
+                    )
+                }
+                _ => {
+                    actix_web::error::ErrorInternalServerError(format!(
+                        "failed to query turbopuffer (BM25): {}",
+                        e
+                    ))
+                }
+            }
         })?
     };
 

src/turbopuffer.rs

···
 use anyhow::{Context, Result};
 use reqwest::Client;
 use serde::{Deserialize, Serialize};
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum TurbopufferError {
+    #[error("query too long: {message}")]
+    QueryTooLong { message: String },
+    #[error("turbopuffer API error: {0}")]
+    ApiError(String),
+    #[error("request failed: {0}")]
+    RequestFailed(#[from] reqwest::Error),
+    #[error("{0}")]
+    Other(#[from] anyhow::Error),
+}
+
+#[derive(Debug, Deserialize)]
+struct TurbopufferErrorResponse {
+    error: String,
+    #[allow(dead_code)]
+    status: String,
+}
 
 #[derive(Debug, Serialize)]
 pub struct QueryRequest {
···
             .context(format!("failed to parse query response: {}", body))
     }
 
-    pub async fn bm25_query(&self, query_text: &str, top_k: usize) -> Result<QueryResponse> {
+    pub async fn bm25_query(&self, query_text: &str, top_k: usize) -> Result<QueryResponse, TurbopufferError> {
         let url = format!(
             "https://api.turbopuffer.com/v1/vectors/{}/query",
             self.namespace
···
             "include_attributes": ["url", "name", "filename"],
         });
 
-        log::debug!("turbopuffer BM25 query request: {}", serde_json::to_string_pretty(&request)?);
+        if let Ok(pretty) = serde_json::to_string_pretty(&request) {
+            log::debug!("turbopuffer BM25 query request: {}", pretty);
+        }
 
         let response = self
             .client
···
             .header("Authorization", format!("Bearer {}", self.api_key))
             .json(&request)
             .send()
-            .await
-            .context("failed to send BM25 query request")?;
+            .await?;
 
         if !response.status().is_success() {
             let status = response.status();
             let body = response.text().await.unwrap_or_default();
-            anyhow::bail!("turbopuffer BM25 query failed with status {}: {}", status, body);
+
+            // try to parse turbopuffer error response
+            if let Ok(error_resp) = serde_json::from_str::<TurbopufferErrorResponse>(&body) {
+                // check if it's a query length error
+                if error_resp.error.contains("too long") && error_resp.error.contains("max 1024") {
+                    return Err(TurbopufferError::QueryTooLong {
+                        message: error_resp.error,
+                    });
+                }
+            }
+
+            return Err(TurbopufferError::ApiError(format!(
+                "turbopuffer BM25 query failed with status {}: {}",
+                status, body
+            )));
         }
 
-        let body = response.text().await.context("failed to read response body")?;
+        let body = response.text().await
+            .map_err(|e| TurbopufferError::Other(anyhow::anyhow!("failed to read response body: {}", e)))?;
         log::debug!("turbopuffer BM25 response: {}", body);
 
         let parsed: QueryResponse = serde_json::from_str(&body)
-            .context(format!("failed to parse BM25 query response: {}", body))?;
+            .map_err(|e| TurbopufferError::Other(anyhow::anyhow!("failed to parse BM25 query response: {}", e)))?;
 
         // DEBUG: log first result to see what BM25 returns
         if let Some(first) = parsed.first() {