Claude API OAuth 403错误实战解析：从权限配置到请求签名的最佳实践

1次阅读

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

先看一个典型的错误日志片段，这是使用 Python requests 库调用 Claude API 时的返回结果：

import requests

response = requests.post(
    'https://api.claude.ai/v1/completions',
    headers={'Authorization': 'Bearer expired_token'},
    json={'prompt': 'Hello Claude'}
)
# 返回结果：# {
#   "error": {
#     "code": 403,
#     "message": "The request is forbidden",
#     "type": "auth_error"
#   }
# }

403 错误的第一个常见原因是权限作用域 (Scope) 不足。以下是 AWS IAM 策略的最小权限配置示例（假设我们需要 completions API 的读写权限）：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["claude:CreateCompletion"],
      "Resource": "arn:aws:claude:::version/v1/completions"
    }
  ]
}

关键要点：

遵循最小权限原则，不要赋予 * 通配符权限
明确指定 Resource ARN 路径
生产环境建议附加条件限制（如 IP 白名单）

Python 示例展示规范的签名流程（以 HMAC-SHA256 为例）：

import hmac
import hashlib
import base64
from datetime import datetime
import urllib.parse

def sign_request(secret_key, method, path, body='', query_params=None):"""
    :param secret_key: IAM 用户密钥
    :param method: HTTP 方法（GET/POST 等）:param path: API 路径（如 /v1/completions）:param body: 请求体 JSON 字符串
    :param query_params: 查询参数字典
    :return: Base64 编码的签名
    """
    # 1. 规范化请求参数
    timestamp = datetime.utcnow().strftime('%Y%m%dT%H%M%SZ')
    query_str = urllib.parse.urlencode(sorted(query_params.items())) if query_params else ''

    # 2. 构建待签名字符串
    canonical_request = f"{method}\n{path}\n{query_str}\n{body}"
    string_to_sign = f"CLAUDE-HMAC-SHA256\n{timestamp}\n{canonical_request}"

    # 3. 计算签名
    signature = hmac.new(secret_key.encode('utf-8'),
        string_to_sign.encode('utf-8'),
        hashlib.sha256
    ).digest()

    return base64.b64encode(signature).decode('utf-8')

以下是带有自动刷新功能的令牌管理器实现：

from datetime import datetime, timedelta
import requests

class TokenManager:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._expires_at = None

    @property
    def token(self):
        if self._is_expired:
            self._refresh_token()
        return self._token

    @property
    def _is_expired(self):
        return not self._expires_at or datetime.now() >= self._expires_at

    def _refresh_token(self):
        auth = requests.auth.HTTPBasicAuth(self.client_id, self.client_secret)
        response = requests.post(
            'https://api.claude.ai/oauth2/token',
            auth=auth,
            data={'grant_type': 'client_credentials'}
        )
        response.raise_for_status()
        token_data = response.json()
        self._token = token_data['access_token']
        self._expires_at = datetime.now() + timedelta(seconds=token_data['expires_in'] - 60)  # 提前 1 分钟过期

import requests
from requests.exceptions import HTTPError
from time import sleep
from functools import wraps

class ClaudeAPIClient:
    MAX_RETRIES = 3
    RETRY_DELAY = 1

    def __init__(self, token_manager):
        self.token_manager = token_manager

    def api_call(self, method, endpoint, **kwargs):
        """带重试机制的 API 调用封装"""
        headers = {'Authorization': f'Bearer {self.token_manager.token}',
            'Content-Type': 'application/json'
        }

        for attempt in range(self.MAX_RETRIES):
            try:
                response = requests.request(
                    method,
                    f'https://api.claude.ai{endpoint}',
                    headers=headers,
                    **kwargs
                )
                response.raise_for_status()
                return response.json()
            except HTTPError as e:
                if e.response.status_code == 403 and attempt < self.MAX_RETRIES - 1:
                    sleep(self.RETRY_DELAY * (attempt + 1))
                    continue
                raise

    @staticmethod
    def handle_errors(f):
        """错误处理装饰器"""
        @wraps(f)
        def wrapper(*args, **kwargs):
            try:
                return f(*args, **kwargs)
            except HTTPError as e:
                if e.response.status_code == 403:
                    print(f"权限错误: {e.response.json().get('error', {}).get('message')}")
                raise
        return wrapper