先给结论：如果你的 Python 脚本调 API 返回 403，而完全相同的请求用 curl 是 200，先别怀疑 key。大概率是urllib/requests的默认 User-Agent 被 CDN 的 WAF 拦了——它返回的 403 和「鉴权失败」的 403 长得几乎一样，但根本不是一回事。
判别只要一步：看 403 的响应体。
| 响应体长什么样 | 真正的原因 |
|---|---|
纯文本error code: 1010 | WAF 拦截，跟你的 key 无关 |
JSON{"error":{"type":"authentication_error",...}} | 鉴权真的失败了 |
JSON{"error":{"type":"permission_error",...}} | key 有效但没这个权限 |
下面是我实际走过的三条错误排查路径，以及最后怎么定位的。命令都能直接复制运行。
实测环境：WSL2 (Ubuntu) + Python 3.12，端点用的是 Code2AI（code2ai.codes）的 Anthropic 兼容网关，前面挂着 Cloudflare。任何前置 CDN 的端点都会复现同样的现象。
一、现象：同端点、同 key、同 payload，两个客户端两个结果
我在跑一个自检脚本，四项检查全部返回 403。脚本本身逻辑很简单，就是往/v1/messages发几个最小请求。
① 假模型名探测 ⚠️ 无法确认 HTTP403，响应不是 Anthropic 的`{"type":"error","error":{...}}`结构 ② 上游响应头 ⚠️ 无法确认 ③ prompt caching ⚠️ 无法确认 HTTP403④ usage 字段结构 ⛔ 请求失败四项全灭，看起来像是这个端点整个不可用，或者 key 废了。
但换 curl 发同一个请求：
curl-sS-XPOST"$ANTHROPIC_BASE_URL/v1/messages"\-H"content-type: application/json"\-H"x-api-key:$ANTHROPIC_AUTH_TOKEN"\-H"anthropic-version: 2023-06-01"\-d'{"model":"claude-sonnet-5","max_tokens":8, "messages":[{"role":"user","content":"hi"}]}'\-w"\n[HTTP %{http_code}]\n"{"id":"msg_01d6f8...","type":"message","role":"assistant","content":[{"type":"text","text":"Hi! How can I help you today"}],"usage":{"input_tokens":1593,"output_tokens":105,...}}[HTTP200]200。同一个 key，同一个 payload，同一台机器，差别只在客户端。
二、三条错误的排查路径（我全走了一遍）
排到这一步很容易往三个方向猜，这三个方向都是错的。写下来省得你重复走。
| 猜测 | 怎么验证 | 实测结果 |
|---|---|---|
| key 无效或过期 | 换 curl 打同一个请求 | ❌ 200，key 是好的 |
| 鉴权头形式不对 | x-api-key与Authorization: Bearer各打一次 | ❌ 两种都 200 |
| 端点挂了 / 路径不对 | 不带任何凭证打一次，看它怎么回 | ❌ 端点活得好好的 |
2.1 别急着换 key
最直觉的反应是「key 是不是废了」。验证成本很低，换个客户端打一次就知道：
curl-sS-o/dev/null-w"%{http_code}\n"-XPOST"$ANTHROPIC_BASE_URL/v1/messages"\-H"content-type: application/json"-H"x-api-key:$ANTHROPIC_AUTH_TOKEN"\-H"anthropic-version: 2023-06-01"\-d'{"model":"claude-sonnet-5","max_tokens":8,"messages":[{"role":"user","content":"hi"}]}'返回 200 就说明 key 没问题，问题在你的客户端。这一条能砍掉一大半排查方向。
2.2 两种鉴权头都试一次
Anthropic 协议用x-api-key，但很多兼容网关同时接受Authorization: Bearer。如果只试了一种，容易误判成「这个端点不认我的鉴权方式」。
实测两种都是 200：
# 形式一-H"x-api-key:$ANTHROPIC_AUTH_TOKEN"# 形式二-H"Authorization: Bearer$ANTHROPIC_AUTH_TOKEN"顺带一提，这两种都支持是兼容网关的常见做法，不代表任何异常。
2.3 不带凭证打一次——这一步信息量最大
这是我认为最被低估的一条排查动作：故意不带 key 发一个请求，看端点怎么拒绝你。
curl-sS-XPOST"$ANTHROPIC_BASE_URL/v1/messages"\-H'content-type: application/json'-d'{}'{"error":{"type":"invalid_request_error","message":"API key required. Use 'x-api-key' or 'Authorization: Bearer' header","request_id":"c2a-990d2533"}}这一个请求同时告诉你三件事：
- 端点是活的，能正常处理请求
- 它的错误响应是标准 JSON 结构，带
type和request_id - 它接受哪些鉴权头——直接写在报错里了
第 2 点是关键：既然这个端点拒绝请求时会返回结构化 JSON，那我脚本收到的那个非 JSON的 403，就一定不是这个端点发出来的。
是中间有人替它回了。
三、真正的原因：默认 User-Agent
urllib不设置 User-Agent 时，默认发的是Python-urllib/3.12。Cloudflare 一类的 WAF 会直接拒掉这类特征明显的客户端签名。
它返回的东西长这样：
HTTP403error code:1010纯文本，没有 JSON 结构。Cloudflare 的 1010 是「基于浏览器签名拒绝访问」。
这个 403 的迷惑性在于：
- 状态码和「鉴权失败」完全一样
- 大部分客户端代码只看
status_code，不看 body - 于是它被当成「key 不对」或「没权限」，排查方向从第一步就偏了
四、控制变量确认：只改 UA
要坐实这个判断，把其他变量全固定住，只改 User-Agent跑一次对照：
importos,json,urllib.request,urllib.error BASE=os.environ["ANTHROPIC_BASE_URL"]BODY=json.dumps({"model":"claude-sonnet-5","max_tokens":8,"messages":[{"role":"user","content":"hi"}]}).encode()defgo(ua):h={"content-type":"application/json","x-api-key":os.environ["ANTHROPIC_AUTH_TOKEN"],"anthropic-version":"2023-06-01"}ifua:h["user-agent"]=ua req=urllib.request.Request(BASE+"/v1/messages",data=BODY,headers=h,method="POST")try:r=urllib.request.urlopen(req,timeout=30)returnf"HTTP{r.status}"excepturllib.error.HTTPErrorase:returnf"HTTP{e.code}body:{e.read()[:60].decode('utf-8','ignore')}"print("默认 UA:",go(None))print("普通 UA:",go("my-tool/1.0"))实测输出：
默认 UA: HTTP403body: error code:1010普通 UA: HTTP200一行 header 的差别。其余全部相同。
修复就是给你的客户端一个正常的 UA。建议报上工具自己的身份，而不是伪装成浏览器——目的是可被识别，不是绕过：
USER_AGENT="my-tool/1.0 (+https://github.com/yourname/yourrepo)"requests库默认 UA 是python-requests/2.x，同样会被拦，处理方式一样。
五、同一家族的另外两类假象
「表现像 A、实际是 B」的问题不止这一个。下面两类同样高频，同样会把人带偏。
5.1 代理环境变量：看起来像「端点不通」
本机配过http_proxy/https_proxy，而那个代理地址已经不可用了。于是每个请求都要先去撞一次超时，最后报连接失败——看起来和「端点挂了」一模一样。
诊断：
env|grep-iproxy如果有输出，先摘掉再测：
env-uhttp_proxy-uhttps_proxy-uHTTP_PROXY-uHTTPS_PROXY\curl-sS-o/dev/null-w"%{http_code}\n""$ANTHROPIC_BASE_URL/v1/messages"-XPOST-d'{}'自检脚本里最好直接把这几个变量摘掉——你要测的是端点，不是本机的网络配置：
forkin("http_proxy","https_proxy","HTTP_PROXY","HTTPS_PROXY","all_proxy","ALL_PROXY"):os.environ.pop(k,None)这个现象的完整诊断流程我单独写过一份请求全部超时的排查记录，里面按「本机 → DNS → 端点」分层给了命令。
5.2base_url多写了一段：404 而不是 403
配ANTHROPIC_BASE_URL时把/v1/messages也写进去了：
# ❌ 错误exportANTHROPIC_BASE_URL="https://example.com/v1/messages"客户端会自己补/v1/messages，实际请求路径变成/v1/messages/v1/messages，然后吃一个莫名其妙的 404。写到域名为止就行：
# ✅ 正确exportANTHROPIC_BASE_URL="https://example.com"判别方法是直接看实际请求的完整 URL。这个坑和它的几种变体我整理在ANTHROPIC_BASE_URL 配置 404 的排查里。
六、一个通用原则：排查外部端点，先建两个对照组
上面三类假象的共同点是——故障现象出现的位置，和故障原因所在的位置，不是同一个地方。报错在你的脚本里，原因在 CDN、在本机环境变量、在配置字符串里。
想快速定位，动手改代码之前先建两个对照组：
| 对照组 | 怎么做 | 能排除什么 |
|---|---|---|
| 换客户端 | 同一个请求用 curl 再打一次 | 区分「端点问题」和「客户端问题」 |
| 去掉凭证 | 故意不带 key 打一次 | 确认端点活着、看清它的错误结构长什么样 |
两条都跑完，绝大多数「403 / 404 / 超时」类问题的方向就定了。剩下的才值得去读代码。
这类排查我整理成了一份手册，放在 claude-code-cn-setup（MIT）——按「安装 / 请求 / 升级」三层分开，每个报错都给了可直接复制的诊断命令。本文这个 UA 的坑收在docs/troubleshooting.md；另外一项更难自己想到的是MTU 黑洞：小请求正常、一发长内容就卡死，因为路径 MTU 发现依赖的 ICMP 被中间设备丢了，大包静默进黑洞——表现是「卡住」而不是「报错」。
FAQ
Q：为什么 curl 能过，Python 不能？
curl 默认会发User-Agent: curl/8.x，WAF 通常放行；urllib默认发Python-urllib/3.x，属于被拦截的特征。差别只在这一个 header。
Q：换requests库会不会好一点？
不会。requests默认 UA 是python-requests/2.x，同样在拦截名单里。显式设置 UA 才是解法。
Q：自己加 User-Agent 算不算绕过风控？
看你加成什么。报上工具自己的名字和仓库地址是标准做法，HTTP 规范里 UA 本来就是用于标识客户端的；把 UA 伪装成 Chrome 浏览器则是另一回事。这两者的区别是「让我可以被识别」和「让我看起来像别人」。
Q：怎么快速确认是 WAF 拦截还是端点本身拒绝？
看 403 的响应体。WAF 返回的通常是纯文本或一整页 HTML；API 端点返回的是带type和request_id的结构化 JSON。另外看响应头有没有CF-RAY、Server: cloudflare这类 CDN 特征。
Q：状态码就一定能说明问题吗？
不能，这正是本文的主题。403 可能来自 WAF、可能来自鉴权、可能来自权限；404 可能是路径拼错、可能是模型名不存在。状态码只是入口，响应体才是证据。
小结
| 现象 | 先查什么 | 而不是 |
|---|---|---|
| 脚本 403、curl 200 | 客户端 User-Agent | 换 key |
| 403 body 是纯文本 | CDN / WAF | 鉴权配置 |
| 所有请求超时 | env | grep -i proxy | 端点可用性 |
| 配置看着都对却 404 | base_url是否多写了/v1/messages | 重装客户端 |
排查外部端点的时候，先固定变量，再改代码。换个客户端打一次、去掉凭证打一次，这两个动作加起来不到一分钟，能省掉一下午。
