Claude Code API 错误处理全指南：从常见错误到高效调试

1次阅读

共计 3704 个字符，预计需要花费 10 分钟才能阅读完成。

在集成 Claude Code API 时，开发者可能会遇到多种类型的错误。这些错误大致可以分为以下几类：

认证错误 ：通常由于无效的 API 密钥或权限不足导致。错误代码一般以401 或403开头。
限流错误：当请求频率超过 API 限制时触发。错误代码通常为429。
参数错误：请求参数缺失或格式不正确。错误代码多为400。
服务器错误 ：API 服务端出现问题。错误代码为5xx 系列。
网络错误：由于网络问题导致的连接超时或中断。

查看 HTTP 状态码：这是最直接的错误来源指示。
解析响应体：大多数 API 错误都会在响应体中提供详细的错误信息。
查阅官方文档：对照文档中的错误代码表进行匹配。
记录完整请求 / 响应：包括 headers、body 和时间戳，便于后续分析。

import requests
from requests.exceptions import RequestException
import time

class ClaudeAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.claude.ai/v1"
        self.max_retries = 3
        self.retry_delay = 1

    def make_request(self, endpoint, method='GET', params=None, data=None):
        headers = {"Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        url = f"{self.base_url}/{endpoint}"

        for attempt in range(self.max_retries):
            try:
                response = requests.request(
                    method,
                    url,
                    headers=headers,
                    params=params,
                    json=data
                )

                # 检查响应状态码
                if response.status_code == 200:
                    return response.json()
                elif response.status_code == 429:
                    # 限流错误，按 Retry-After 头延迟或使用默认延迟
                    retry_after = int(response.headers.get('Retry-After', self.retry_delay))
                    time.sleep(retry_after)
                    continue
                else:
                    # 其他错误，解析错误信息
                    error_data = response.json()
                    raise ClaudeAPIError(
                        status_code=response.status_code,
                        error_code=error_data.get('code'),
                        message=error_data.get('message')
                    )
            except RequestException as e:
                if attempt == self.max_retries - 1:
                    raise ClaudeAPIError(
                        status_code=None,
                        error_code="NETWORK_ERROR",
                        message=str(e)
                    )
                time.sleep(self.retry_delay)
                continue

        raise ClaudeAPIError(
            status_code=None,
            error_code="MAX_RETRIES_EXCEEDED",
            message=f"Failed after {self.max_retries} attempts"
        )

class ClaudeAPIError(Exception):
    def __init__(self, status_code, error_code, message):
        self.status_code = status_code
        self.error_code = error_code
        self.message = message
        super().__init__(f"{status_code} - {error_code}: {message}")

const axios = require('axios');

class ClaudeAPI {constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.claude.ai/v1';
    this.maxRetries = 3;
    this.retryDelay = 1000; // ms
  }

  async makeRequest(endpoint, method = 'GET', params = {}, data = {}) {
    const headers = {'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json'
    };

    const url = `${this.baseUrl}/${endpoint}`;

    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        const response = await axios({
          method,
          url,
          headers,
          params,
          data
        });

        if (response.status === 200) {return response.data;}

        // 非 200 状态码处理
        if (response.status === 429) {const retryAfter = parseInt(response.headers['retry-after'] || this.retryDelay);
          await new Promise(resolve => setTimeout(resolve, retryAfter));
          continue;
        }

        throw new ClaudeAPIError(
          response.status,
          response.data?.code,
          response.data?.message
        );
      } catch (error) {if (attempt === this.maxRetries - 1) {if (error.response) {
            throw new ClaudeAPIError(
              error.response.status,
              error.response.data?.code,
              error.response.data?.message
            );
          } else {
            throw new ClaudeAPIError(
              null,
              'NETWORK_ERROR',
              error.message
            );
          }
        }

        await new Promise(resolve => setTimeout(resolve, this.retryDelay));
      }
    }

    throw new ClaudeAPIError(
      null,
      'MAX_RETRIES_EXCEEDED',
      `Failed after ${this.maxRetries} attempts`
    );
  }
}

class ClaudeAPIError extends Error {constructor(statusCode, errorCode, message) {super(`${statusCode} - ${errorCode}: ${message}`);
    this.statusCode = statusCode;
    this.errorCode = errorCode;
    this.message = message;
  }
}