PDF Insight Pro uses standard HTTP status codes for all error conditions and returns JSON error bodies that follow FastAPI’sDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/Jatin-Mehra119/PDF-Insight-Beta/llms.txt
Use this file to discover all available pages before exploring further.
HTTPException format. Every error response carries a detail field containing a human-readable description of what went wrong. Error messages are centralised in the ErrorMessages class in configs/config.py, so the strings documented here are stable across releases.
Error Response Format
When a request cannot be fulfilled, the API returns a JSON object with the following shape:HTTPException. The detail value is always a plain string — never a nested object — making it straightforward to surface directly to end users or log for debugging.
The
ErrorResponse Pydantic model (models/models.py) additionally defines status and optional type fields. These are used when the application constructs error objects programmatically; raw HTTPException responses from route handlers follow the single-field format shown above.HTTP Status Codes
| Code | Meaning | When it occurs |
|---|---|---|
400 | Bad Request | The request body is semantically invalid — the query field is empty, or the query is shorter than 3 characters. |
404 | Not Found | The supplied session_id does not match any active session, or the session has been removed. |
500 | Internal Server Error | PDF processing failure, query/agent processing failure, incomplete session data, or a missing server-side API key. |
A
422 Unprocessable Entity is returned by FastAPI automatically when request body fields are missing or have the wrong type, before the route handler is even invoked. This is separate from the application-level errors listed above.All Error Messages
All error message strings originate fromconfigs/config.py → class ErrorMessages. The table below groups them by HTTP status code and documents when each is raised.
Validation Errors — 400 Bad Request
These errors are raised inside chat_handler before any session or LLM interaction occurs.
| Message | Condition |
|---|---|
"Query cannot be empty" | The query field in ChatRequest is an empty string or contains only whitespace. |
"Query must be at least 3 characters long" | The query field, after stripping whitespace, is fewer than 3 characters. |
Session Errors — 404 Not Found
These errors are raised when the provided session_id cannot be resolved to a live session.
| Message | Raised by | Condition |
|---|---|---|
"Session not found" | /chat-history, /clear-history | The session_id does not match any stored session. |
"Session not found or expired. Please upload a document first." | POST /chat | The session_id is not present in the session store at query time. |
"Session not found or could not be removed" | /remove-pdf | The session_id is unknown or the session could not be cleaned up. |
Processing Errors — 500 Internal Server Error
These errors indicate a failure during server-side processing. The detail field may include the underlying Python exception message for diagnostics.
| Message | Raised by | Condition |
|---|---|---|
"Session data is incomplete. Please upload the document again." | POST /chat | The session exists but is missing required keys (e.g. the FAISS index or chunk list were not stored correctly). |
"Error processing PDF: {error}" | POST /upload-pdf | An exception was raised while saving, parsing, or chunking the uploaded PDF. {error} is replaced with the exception message. |
"Error processing query: {error}" | POST /chat | An unhandled exception occurred in the RAG agent or LLM call. {error} is replaced with the exception message. |
"GROQ_API_KEY is not set for Groq Llama models." | POST /upload-pdf, POST /chat | The GROQ_API_KEY environment variable is absent or empty on the server. |
Client Handling Recommendations
How should I handle 404 session errors?
How should I handle 404 session errors?
Sessions are stored in memory and are not persisted to disk between server restarts. If you receive a
404 with any of the session-not-found messages, the session is gone and cannot be recovered.Recommended approach:- Catch any
404response from/chat,/chat-history,/clear-history, or/remove-pdf. - Re-upload the PDF to
POST /upload-pdfto obtain a freshsession_id. - Replay the conversation from the client side if continuity matters to your use case.
session_id in your client’s local storage so you can detect stale sessions early and prompt the user to re-upload before they attempt to send a query.How should I handle 500 PDF processing errors?
How should I handle 500 PDF processing errors?
A
500 from POST /upload-pdf means the server could not parse or chunk the file. The detail field will contain the string "Error processing PDF: " followed by the original Python exception message.Recommended approach:- Verify the file is a valid, non-corrupted PDF. Scanned images saved as PDF without a text layer may produce empty extraction results rather than an error, so also check that
POST /chatreturns meaningful context. - Confirm the file is under the 50 MB server-side limit (
Config.MAX_FILE_SIZE). - Log the full
detailstring — it includes the underlying exception class and message, which is the fastest path to diagnosing unusual encoding or structure issues. - Present a user-friendly message and offer a retry option; transient I/O errors are rare but possible.
How should I handle 500 query processing errors?
How should I handle 500 query processing errors?
A
500 from POST /chat means the RAG agent or LLM call failed after the session was successfully validated. The detail field will contain "Error processing query: " followed by the exception.Recommended approach:- Retry the request once — transient network timeouts to the Groq API are the most common cause.
- If the error persists, simplify the query. The LangChain agent includes a fallback chain, but very long or structurally complex queries with
use_search: truemay occasionally exceed context or rate limits. - Try setting
use_search: falseto eliminate the Tavily tool call from the agent loop and isolate whether the failure is search-related. - If the error message mentions a rate-limit or quota term, apply exponential back-off before retrying.