Error Handling

---

This guide covers error handling strategies for API calls, diagnostics, retry approaches, and solutions to common issues when working with AI-powered documentation pipelines.

API Call Errors

When the documentation pipeline makes requests to the Anthropic API, errors are caught and reported with detailed diagnostic information. The runStep utility function wraps each pipeline stage with comprehensive error handling:

import { APICallError } from "ai";

export async function runStep(label: string, fn: () => Promise<void>): Promise<void> {
  try {
    await fn();
  } catch (error) {
    if (APICallError.isInstance(error)) {
      console.error(`\nAPI error during "${label}":`);
      console.error(`  Status:  ${error.statusCode ?? "unknown"}`);
      console.error(`  Message: ${error.message}`);
      if (error.responseBody) {
        console.error(
          `  Body:    ${typeof error.responseBody === "string" ? error.responseBody : JSON.stringify(error.responseBody)}`,
        );
      }
      console.error(`\nCheck that the model ID is valid and accessible with your API key.`);
      process.exit(1);
    }
    throw error;
  }
}

The function distinguishes between API errors (which cause the pipeline to exit gracefully) and other errors (which are re-thrown for handling elsewhere).

Error Diagnostics

When an API error occurs, the diagnostic output includes:

• Label: The name of the pipeline step that failed
• Status Code: HTTP status code from the API response (if available)
• Error Message: Human-readable description of the failure
• Response Body: The full API response body for further investigation
• Helpful Hint: Reminder to validate model IDs and API key permissions

This information appears during the five-stage pipeline: Building file tree, Extracting structure, Summarising, Planning topics, and Writing docs. Each stage is wrapped with runStep, ensuring errors surface with context about where the pipeline failed.

Retry Strategies

The current implementation implements immediate failure on API errors. For production use, consider implementing exponential backoff retry logic:

export async function runStepWithRetry(
  label: string,
  fn: () => Promise<void>,
  maxRetries: number = 3,
  baseDelay: number = 1000,
): Promise<void> {
  let lastError: Error | null = null;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      await fn();
      return;
    } catch (error) {
      lastError = error;
      if (attempt < maxRetries && shouldRetry(error)) {
        const delay = baseDelay * Math.pow(2, attempt);
        console.warn(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms...`);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Transient errors (rate limiting, temporary network issues) benefit from retry logic, while permanent errors (invalid API keys, bad requests) should fail immediately.

Common Issues

Missing ANTHROPIC_API_KEY: The pipeline requires the ANTHROPIC_API_KEY environment variable. If not set, the command exits with an error before attempting any API calls:

if (!process.env.ANTHROPIC_API_KEY) {
  console.error("Error: ANTHROPIC_API_KEY is not set.");
  process.exit(1);
}

Invalid Model ID: The error message suggests checking that the model ID is valid and accessible. Verify the model is available in your Anthropic account and the API key has sufficient permissions.

Database Permissions: The pipeline persists state in a local SQLite database (.docs-mcp.db). Ensure the repository directory is writable.

Rate Limiting: API quota exceeded errors require waiting before retrying. Check your Anthropic API usage and rate limits.

Network Issues: Temporary connectivity problems may cause transient errors. These are good candidates for retry logic with exponential backoff.