classifyApiError() — mcp Function Reference

Architecture documentation for the classifyApiError() function in api-helpers.ts from the mcp codebase.

Function typescript UtilityLibrary ErrorClassifier called by 2

Entity Profile

UtilityLibrary→ ErrorClassifier→ classifyApiError() — mcp Function Reference

Dependency Diagram

graph TD
  1595e523_decc_c3ce_72e9_f77eb66bef69["classifyApiError()"]
  4bef1572_5a60_651d_3247_2779d2e6bd57["api-helpers.ts"]
  1595e523_decc_c3ce_72e9_f77eb66bef69 -->|defined in| 4bef1572_5a60_651d_3247_2779d2e6bd57
  b0737d71_130b_01b2_dbd7_14cb5f04946b["handler()"]
  b0737d71_130b_01b2_dbd7_14cb5f04946b -->|calls| 1595e523_decc_c3ce_72e9_f77eb66bef69
  f6b4d8d8_12fd_640f_c545_748d0e260bf0["handler()"]
  f6b4d8d8_12fd_640f_c545_748d0e260bf0 -->|calls| 1595e523_decc_c3ce_72e9_f77eb66bef69
  style 1595e523_decc_c3ce_72e9_f77eb66bef69 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

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: {