Error Reference
HTTP Status Codes
Section titled “HTTP Status Codes”| Code | Meaning | When |
|---|---|---|
| 200 | OK | Successful request |
| 202 | Accepted | Async operation queued (audio transcription, MCP notifications) |
| 204 | No Content | MCP session terminated |
| 400 | Bad Request | Invalid input, missing required fields |
| 401 | Unauthorized | Missing or invalid auth token |
| 403 | Forbidden | MCP session belongs to a different user |
| 404 | Not Found | Resource doesn’t exist, or MCP session has expired |
| 426 | Upgrade Required | WebSocket upgrade header missing on a WebSocket endpoint |
| 502 | Bad Gateway | Upstream service failure (e.g., Clerk metadata fetch failed) |
GraphQL Errors
Section titled “GraphQL Errors”GraphQL always returns HTTP 200 for successfully parsed queries, even when the operation itself fails. Errors appear in the errors array of the response body.
{ "data": null, "errors": [ { "message": "Unexpected error.", "extensions": { ... } } ]}Error messages are masked in production for security. Client-facing messages are intentionally generic to avoid leaking internal state. Detailed error information is available in server logs.
JSON-RPC Error Codes (MCP)
Section titled “JSON-RPC Error Codes (MCP)”MCP uses JSON-RPC 2.0. Protocol-level errors use standard JSON-RPC error codes:
| Code | Name | Meaning |
|---|---|---|
| -32700 | Parse Error | Invalid JSON in the request body |
| -32600 | Invalid Request | Malformed JSON-RPC 2.0 structure (missing jsonrpc, method, etc.) |
| -32601 | Method Not Found | Unknown method or tool name |
| -32602 | Invalid Params | Missing or invalid required parameters |
| -32603 | Internal Error | Unhandled exception during processing |
MCP Tool Errors
Section titled “MCP Tool Errors”Tool-level errors (e.g., “document not found”) are returned as successful JSON-RPC responses with isError: true in the result. This distinguishes business logic errors from protocol errors.
{ "jsonrpc": "2.0", "id": 1, "result": { "content": [{ "type": "text", "text": "Error: Document not found" }], "isError": true }}401 Response Headers
Section titled “401 Response Headers”All 401 responses include a WWW-Authenticate header for OAuth discovery:
WWW-Authenticate: Bearer resource_metadata="https://api.ontrove.sh/.well-known/oauth-protected-resource"MCP clients use this header to automatically discover the Clerk authorization server and initiate the OAuth flow.
Common Issues
Section titled “Common Issues””Missing authorization”
Section titled “”Missing authorization””No token was provided. Include a Bearer token in the Authorization header or a session token in the __session cookie.
”Invalid or expired token”
Section titled “”Invalid or expired token””The Clerk session token has expired or is malformed. Obtain a fresh token from Clerk. Session tokens typically expire after a few minutes and must be refreshed using the Clerk SDK.
”Session user mismatch”
Section titled “”Session user mismatch””The MCP session was created by a different user than the one in the current auth token. Each MCP session is bound to the user who created it. Create a new session with the correct credentials.
”Invalid or expired session”
Section titled “”Invalid or expired session””The MCP session ID in the MCP-Session-Id header does not correspond to an active session. HTTP transport sessions expire after 1 hour. Start a new session by sending an initialize request without a session ID.
”Connector not found”
Section titled “”Connector not found””The connector ID provided does not exist in your database. Verify the ID using trove_list_connectors or the connectors GraphQL query.
”Document not found”
Section titled “”Document not found””The document ID does not exist. Document IDs are 16-character hex strings. Verify the ID from your search results (the value inside [doc:...] brackets in MCP responses).