classifyApiError() — mcp Function Reference

Source Code

src/utils/api-helpers.ts lines 61–193

export function classifyApiError(error: any): StructuredError {
  // Guard against non-Error throws (strings, nulls, plain objects)
  if (!error || typeof error !== 'object') {
    return {
      type: 'internal_error',
      message: typeof error === 'string' ? error : 'An unexpected error occurred.',
      code: 'UNKNOWN_ERROR',
      recoverable: false,
      reportable: true,
      repo: REPORT_REPO,
      suggestion: REPORT_SUGGESTION,
      details: { errorType: typeof error },
    };
  }

  // Fast-fail: no pre-computed cache and API fallback disabled
  if (error.code === 'NO_CACHE') {
    return {
      type: 'cache_error',
      message: error.message || 'No pre-computed graph available for this repository.',
      code: 'NO_CACHE',
      recoverable: false,
      suggestion: 'Use grep, find, and file reading to explore the codebase instead. Or run the precache command and set SUPERMODEL_CACHE_DIR.',
    };
  }

  if (error.response) {
    const status = error.response.status;

    switch (status) {
      case 401:
        return {
          type: 'authentication_error',
          message: 'Invalid or missing API key.',
          code: 'INVALID_API_KEY',
          recoverable: false,
          suggestion: 'Set the SUPERMODEL_API_KEY environment variable and restart the MCP server.',
          details: { apiKeySet: !!process.env.SUPERMODEL_API_KEY, httpStatus: 401 },
        };
      case 403:
        return {
          type: 'authorization_error',
          message: 'API key does not have permission for this operation.',
          code: 'FORBIDDEN',
          recoverable: false,
          suggestion: 'Verify your API key has the correct permissions. Contact support if unexpected.',
          details: { httpStatus: 403 },
        };
      case 404:
        return {
          type: 'not_found_error',
          message: 'API endpoint not found.',
          code: 'ENDPOINT_NOT_FOUND',
          recoverable: false,
          suggestion: 'Check SUPERMODEL_BASE_URL environment variable. Default: https://api.supermodeltools.com',
          details: { baseUrl: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com', httpStatus: 404 },
        };
      case 429:
        return {
          type: 'rate_limit_error',
          message: 'API rate limit exceeded.',
          code: 'RATE_LIMITED',
          recoverable: true,
          suggestion: 'Wait 30-60 seconds and retry. Consider analyzing smaller subdirectories to reduce API calls.',
          details: { httpStatus: 429 },
        };
      case 500:
      case 502:
      case 503:
      case 504:
        return {
          type: 'internal_error',
          message: `Supermodel API server error (HTTP ${status}).`,
          code: 'SERVER_ERROR',
          recoverable: true,
          reportable: true,
          repo: REPORT_REPO,
          suggestion: 'The API may be temporarily unavailable. Wait a few minutes and retry. If persistent, open an issue at https://github.com/supermodeltools/mcp/issues with the error details, or fork the repo and open a PR with a fix.',
          details: { httpStatus: status },
        };
      default: {
        const isServerError = status >= 500;
        return {
          type: isServerError ? 'internal_error' : 'validation_error',
          message: `API request failed with HTTP ${status}.`,
          code: 'API_ERROR',
          recoverable: isServerError,
          ...(isServerError && {
            reportable: true,
            repo: REPORT_REPO,
            suggestion: 'The API may be temporarily unavailable. Wait a few minutes and retry. If persistent, open an issue at https://github.com/supermodeltools/mcp/issues with the error details, or fork the repo and open a PR with a fix.',
          }),
          ...(!isServerError && { suggestion: 'Check the request parameters and base URL configuration.' }),
          details: { httpStatus: status },
        };
      }
    }
  }

  if (error.request) {
    // Distinguish timeout from general network failure
    if (error.code === 'UND_ERR_HEADERS_TIMEOUT' || error.code === 'UND_ERR_BODY_TIMEOUT' || error.message?.includes('timeout')) {
      return {
        type: 'timeout_error',
        message: 'API request timed out. The codebase may be too large for a single analysis.',
        code: 'REQUEST_TIMEOUT',
        recoverable: true,
        suggestion: 'Analyze a smaller subdirectory (e.g. directory="/repo/src/core") or increase SUPERMODEL_TIMEOUT_MS.',
      };
    }

    return {
      type: 'network_error',
      message: 'No response from Supermodel API server.',
      code: 'NO_RESPONSE',
      recoverable: true,
      suggestion: 'Check network connectivity. Verify the API is reachable at the configured base URL.',
      details: { baseUrl: process.env.SUPERMODEL_BASE_URL || 'https://api.supermodeltools.com' },
    };
  }

  // Catch-all for unexpected errors - include the actual message
  return {
    type: 'internal_error',
    message: error.message || 'An unexpected error occurred.',
    code: 'UNKNOWN_ERROR',
    recoverable: false,
    reportable: true,
    repo: REPORT_REPO,
    suggestion: REPORT_SUGGESTION,
    details: { errorType: error.name || 'Error' },
  };
}