Overview
Error responses are returned when a request fails due to validation errors, API issues, network problems, or other exceptional conditions. All error responses follow a consistent structure.
Response Structure
A descriptive error message explaining what went wrong
Status indicator for the request. Always "failed" for error responses
The search query that was attempted (if available)
The search type that was requested (e.g., "web", "news", "general")
The analysis mode that was requested (e.g., "basic", "comprehensive")
ISO8601 timestamp of when the error occurred
Unique identifier for this request in the format req_{timestamp}_{random}
The from_date parameter that was provided (if any)
The to_date parameter that was provided (if any)
Common Error Types
API Key Errors
Occur when the XAI_API_KEY is missing, invalid, or unauthorized.
{
"error": "API service is not healthy - missing XAI_API_KEY",
"status": "failed",
"query": "latest AI developments",
"search_type": "web",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_a1b2c3d4e",
"from_date": null,
"to_date": null
}
XAI_API_KEY environment variable is set correctly in your Claude Desktop configuration.
Occur when request parameters fail validation checks.
Missing Query
{
"error": "Search query must be a non-empty string",
"status": "failed",
"query": "",
"search_type": "web",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_b2c3d4e5f",
"from_date": null,
"to_date": null
}
Query Too Long
{
"error": "Search query too long (max 1000 characters)",
"status": "failed",
"query": "very long query text...",
"search_type": "web",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_c3d4e5f6g",
"from_date": null,
"to_date": null
}
{
"error": "from_date must be in ISO8601 format (YYYY-MM-DD)",
"status": "failed",
"query": "climate change news",
"search_type": "news",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_d4e5f6g7h",
"from_date": "06/01/2025",
"to_date": null
}
Invalid Date Range
{
"error": "from_date must be before to_date",
"status": "failed",
"query": "tech news",
"search_type": "news",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_e5f6g7h8i",
"from_date": "2025-06-20",
"to_date": "2025-06-10"
}
Invalid Max Results
{
"error": "max_results must be between 1 and 20",
"status": "failed",
"query": "AI research",
"search_type": "web",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_f6g7h8i9j",
"from_date": null,
"to_date": null
}
API Rate Limiting
Occur when the xAI API rate limit is exceeded.
{
"error": "API request failed: 429 - Rate limit exceeded. Please try again later.",
"status": "failed",
"query": "breaking news",
"search_type": "news",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_g7h8i9j0k",
"from_date": null,
"to_date": null
}
Network and Timeout Errors
Occur when network connectivity issues or request timeouts happen.
Timeout Error
{
"error": "Request timeout after 30000ms",
"status": "failed",
"query": "comprehensive analysis query",
"search_type": "web",
"analysis_mode": "comprehensive",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_h8i9j0k1l",
"from_date": null,
"to_date": null
}
- Try using basic mode instead of comprehensive mode
- Increase the
GROK_TIMEOUT environment variable
- Check network connectivity
Network Error
{
"error": "Failed to make API request: Network error - Unable to connect to xAI API",
"status": "failed",
"query": "latest developments",
"search_type": "web",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_i9j0k1l2m",
"from_date": null,
"to_date": null
}
Parsing Errors
Occur when the server cannot parse the API response (rare, as fallback responses are used).
{
"error": "Failed to parse search results: Unexpected response format",
"status": "failed",
"query": "search query",
"search_type": "web",
"analysis_mode": "basic",
"timestamp": "2025-06-24T12:00:00.000Z",
"request_id": "req_1719230400000_j0k1l2m3n",
"from_date": null,
"to_date": null
}
Error Handling Best Practices
Categorizing Errors
Error messages can be categorized by their content:
- API Key Issues: Contains “API key” or “API service is not healthy”
- Validation Errors: Contains “validation”, “format”, “must be”, “too long”
- Rate Limiting: Contains “rate limit” or HTTP status 429
- Timeout Errors: Contains “timeout”
- Network Errors: Contains “network”, “connect”, “connection”
- Parsing Errors: Contains “parse” or “format”
Retry Strategy
The server automatically handles retries for certain error types:
- Rate Limiting: Automatic retry with exponential backoff (up to 3 attempts)
- Network Errors: Automatic retry (up to 3 attempts)
- Timeouts: No automatic retry (adjust
GROK_TIMEOUT instead)
- Validation Errors: No retry (fix input parameters)
- API Key Errors: No retry (fix configuration)
User-Facing Error Messages
When presenting errors to users, consider mapping technical errors to friendly messages:
function getFriendlyErrorMessage(errorResponse) {
const error = errorResponse.error.toLowerCase();
if (error.includes('api key') || error.includes('api service is not healthy')) {
return 'API configuration issue. Please check your XAI_API_KEY settings.';
}
if (error.includes('rate limit')) {
return 'Too many requests. Please wait a moment and try again.';
}
if (error.includes('timeout')) {
return 'Request took too long. Try using basic mode or a simpler query.';
}
if (error.includes('validation') || error.includes('format') || error.includes('must be')) {
return `Invalid input: ${errorResponse.error}`;
}
if (error.includes('network') || error.includes('connect')) {
return 'Network connectivity issue. Please check your internet connection.';
}
return `Search failed: ${errorResponse.error}`;
}
{
"content": [
{
"type": "text",
"text": "{\"error\":\"Error message\",\"status\":\"failed\",...}"
}
],
"isError": true
}
isError: true flag indicates this is an error response at the MCP protocol level.
Debugging with Request IDs
Each error includes a unique request_id that can be used for:
- Tracking specific failed requests
- Correlating errors in logs
- Debugging patterns across multiple requests
The format req_{timestamp}_{random} ensures uniqueness while providing temporal ordering.
Health Check for Diagnostics
Use the health_check tool to diagnose server and API health before investigating specific errors:
{
"server_healthy": false,
"api_healthy": false,
"api_details": {
"hasApiKey": false,
"lastError": "XAI_API_KEY environment variable not set"
}
}
