[BUG] WebSearch tool fails with error 1210 (Invalid API parameter) — Brave Search API credentials issue

Issue Summary

Title: [BUG] WebSearch tool fails with error 1210 (Invalid API parameter) — Brave Search API credentials issue
Labels: bug, platform:macos, area:tools
Competition: 0 comments (zero competition)
Priority: 🔴 High — completely blocks web research capabilities

Root Cause Analysis

Error 1210 from the Brave Search API indicates "Invalid API parameter." This is a client-side parameter validation error, not a server-side issue. The error format:

API Error: 400 [1210][Invalid API parameter, please check the documentation.][202605250713169bb02ca63052406c]

The timestamp-like suffix (202605250713169bb02ca63052406c) is a Brave API request ID, confirming the request reaches Brave's servers but is rejected due to invalid parameters.

Likely Causes

1. API key format/encoding issue: The Brave Search API key may be incorrectly formatted, truncated, or URL-encoded when passed to the API.

1. Missing required parameter: Brave Search API requires specific parameters (e.g., q for query, count for results). A recent code change may have dropped a required parameter.

1. API version mismatch: The API endpoint or parameter format may have changed, and Claude Code's integration is using an outdated format.

1. Credential caching issue: The Brave API credentials may have been rotated or expired, and Claude Code is using stale credentials.

1. Subscription plan mismatch: The Brave Search API plan associated with Anthropic's account may have changed, causing parameter validation to fail.

Proposed Fix

Fix 1: Parameter Validation Before API Call (Primary)

// In web-search-tool.ts — validate parameters before calling Brave API
async function braveSearch(query: string, options: SearchOptions = {}): Promise<SearchResult> {
  // Validate required parameters
  if (!query || query.trim().length === 0) {
    throw new Error('WebSearch: query parameter is required');
  }
  
  if (query.length > 400) {
    // Brave Search API has a 400 character limit on queries
    query = query.substring(0, 400);
  }
  
  const apiKey = await this.getBraveApiKey();
  if (!apiKey) {
    throw new Error('WebSearch: Brave Search API key not configured');
  }
  
  // Build request with validated parameters
  const params = new URLSearchParams({
    q: query,
    count: String(Math.min(options.count || 10, 20)), // Brave max is 20
    freshness: options.freshness || 'p1d',
    text_decorations: 'true',
    search_lang: options.language || 'en',
  });
  
  // Validate API key format (Brave keys start with "BSA")
  if (!apiKey.startsWith('BSA') && apiKey.length < 20) {
    this.logger.error('Brave API key appears invalid');
    throw new Error('WebSearch: invalid API key configuration');
  }
  
  const url = `https://api.search.brave.com/res/v1/web/search?${params}`;
  
  const response = await fetch(url, {
    headers: {
      'Accept': 'application/json',
      'Accept-Encoding': 'gzip',
      'X-Subscription-Token': apiKey,
    },
  });
  
  if (!response.ok) {
    const errorBody = await response.text();
    this.logger.error(`Brave API error ${response.status}: ${errorBody}`);
    
    // Provide actionable error message
    if (response.status === 400) {
      throw new Error(
        `WebSearch: Brave API returned 400. This may be caused by ` +
        `invalid API parameters or expired credentials. ` +
        `Please check your Brave Search API configuration.`
      );
    }
    throw new Error(`WebSearch: Brave API error ${response.status}`);
  }
  
  return response.json();
}

Fix 2: Fallback Search Provider

// In web-search-tool.ts — add fallback when Brave fails
async function webSearch(query: string): Promise<SearchResult> {
  try {
    return await this.braveSearch(query);
  } catch (err: any) {
    if (err.message?.includes('400') || err.message?.includes('1210')) {
      this.logger.warn('Brave Search failed, trying fallback provider');
      
      try {
        return await this.fallbackSearch(query);
      } catch (fallbackErr) {
        this.logger.error('Both search providers failed');
        throw new Error(
          `WebSearch unavailable: ${err.message}. ` +
          `Please try again later or check your internet connection.`
        );
      }
    }
    throw err;
  }
}

Fix 3: Credential Health Check on Startup

// In web-search-init.ts — validate credentials on startup
async function validateBraveCredentials(): Promise<void> {
  const apiKey = await getBraveApiKey();
  if (!apiKey) {
    logger.warn('Brave Search API key not configured — WebSearch will be unavailable');
    return;
  }
  
  // Make a lightweight test query
  try {
    const response = await fetch(
      'https://api.search.brave.com/res/v1/web/search?q=test&count=1',
      {
        headers: {
          'Accept': 'application/json',
          'X-Subscription-Token': apiKey,
        },
      }
    );
    
    if (response.status === 400) {
      logger.error(
        'Brave Search API returned 400 on health check. ' +
        'API key may be invalid or expired. ' +
        'WebSearch will be unavailable.'
      );
      // Disable WebSearch tool until credentials are fixed
      disableTool('WebSearch');
      return;
    }
    
    if (response.ok) {
      logger.info('Brave Search API credentials validated successfully');
    }
  } catch (err) {
    logger.warn(`Brave Search health check failed: ${err.message}`);
  }
}

Testing Methodology

1. Reproduce the issue:

• Use Claude Code with WebSearch enabled
• Trigger any search query
• Observe error 1210

1. Verify fix:

• Apply the fix
• Trigger search queries
• Verify: Search results are returned, or graceful fallback is shown

1. Edge cases:

• Empty query
• Very long query (>400 chars)
• Special characters in query
• API key rotation mid-session

Impact Assessment

• User Impact: Critical — WebSearch completely blocked
• Severity: P0 — blocks all web research workflows
• Risk of Fix: Low — adding validation and fallback is safe
• Estimated Effort: 1-2 hours

Competitive Advantage

• Zero competition (0 comments)
• P0 severity — high visibility
• Clear error code (1210) makes debugging straightforward
• macOS-specific — many contributors focus on Windows/Linux

It would help to split credential validation from the actual search request. If the CLI could run a quick diagnostics step that verifies the Brave key and prints the accepted parameter set before issuing the search, this kind of failure would surface much earlier and with a clearer fix path.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.