AI Error Handler

You are a resilience engineer building robust AI API integrations. The user wants to implement comprehensive error handling, automatic retries with exponential backoff, and intelligent fallback strategies for AI API calls.

What to check first

• Verify which AI provider you're using (OpenAI, Anthropic, Cohere, local LLM) by checking your package.json or imports
• Run npm list to confirm you have axios or node-fetch installed for HTTP requests
• Check if you have a .env file with API_KEY and API_BASE_URL variables set

Steps

1. Define error categories by checking the HTTP status code and error type (rate limit: 429, auth: 401, server: 5xx, timeout: request timeout)
2. Create a retry configuration object with maxRetries (default: 3), initialDelayMs (default: 1000), and backoffMultiplier (default: 2)
3. Implement exponential backoff calculation: delayMs = initialDelayMs * (backoffMultiplier ^ attemptNumber)
4. Add jitter to prevent thundering herd: delayMs * (0.5 + Math.random() * 0.5)
5. Set up fallback strategies: primary provider → secondary provider → cached response → default text
6. Wrap AI API calls in a try-catch that logs errors with context (timestamp, endpoint, payload size, attempt number)
7. Implement circuit breaker pattern to stop retrying after repeated failures within a time window (e.g., 5 failures in 60 seconds)
8. Return structured error responses with success, data, error, retryCount, and fallbackUsed fields

Code

const axios = require('axios');

class AIErrorHandler {
  constructor(config = {}) {
    this.maxRetries = config.maxRetries || 3;
    this.initialDelayMs = config.initialDelayMs || 1000;
    this.backoffMultiplier = config.backoffMultiplier || 2;
    this.circuitBreakerThreshold = config.circuitBreakerThreshold || 5;
    this.circuitBreakerWindow = config.circuitBreakerWindow || 60000;
    this.failureLog = [];
    this.fallbackProviders = config.fallbackProviders || [];
  }

  isCircuitBreakerOpen() {
    const now = Date.now();
    const recentFailures = this.failureLog.filter(
      (timestamp) => now - timestamp < this.circuitBreakerWindow
    );
    return recentFailures.length >= this.circuitBreakerThreshold;
  }

  logFailure() {
    this.failureLog.push(Date.now());
    this.failureLog = this.failureLog.filter(
      (timestamp) => Date.now() - timestamp < this

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Forgetting to handle rate limits — Anthropic returns 429 errors that need exponential backoff
• Hardcoding the model name in 50 places — use a single config so you can swap models in one place
• Not setting a timeout on API calls — a hanging request can lock your worker indefinitely
• Logging API responses with sensitive data — PII can end up in your logs without realizing
• Treating the API as deterministic — same prompt, different output. Test on multiple runs

When NOT to Use This Skill

• For deterministic tasks where regex or rule-based code would work — LLMs add cost and latency for no benefit
• When you need 100% accuracy on a known schema — use structured output APIs or fine-tuning instead
• For real-time low-latency applications under 100ms — even the fastest LLM is too slow

How to Verify It Worked

• Test with malformed inputs, empty strings, and edge cases — APIs often behave differently than docs suggest
• Verify your error handling on all 4xx and 5xx responses — most code only handles the happy path
• Run a load test with 10x your expected traffic — rate limits hit fast
• Check token usage matches your estimate — surprises here become surprises on your bill

Production Considerations

• Set a daily spend cap on your Anthropic console — prevents runaway costs from bugs or attacks
• Use prompt caching for static parts of your prompts — can cut costs by 50-90%
• Stream responses for any user-facing output — perceived latency drops by 70%
• Have a fallback model ready — if Claude is down, you should be able to swap to a backup with one config change