Cloudflare API 认证失败主因是Token权限不足或格式错误：必须使用API Token（非Global Key），显式授权如DNS:Edit、Zone:Read，并通过Authorization: Bearer头传递；Zone ID需域名已接入Cloudflare且状态为Active；DNS更新须传record.ID，不可仅靠name+type；无原生批量接口，限流需手动重试。
Cloudflare API 认证失败：token 权限不足或格式错误
直接用 curl 调试时返回 403 Forbidden 或 {"success":false,"errors":[{"code":6003,"message":"Invalid request headers"}]}，大概率是 token 问题。Cloudflare 要求使用 API Token（非 Global API Key），且必须显式勾选对应权限——比如操作 DNS 记录，需在 Token 设置里添加 DNS:Edit 权限到目标 Zone；若漏掉 Zone:Read，连 Zone ID 查询都会失败。
Go 客户端初始化时，务必通过 Authorization: Bearer <token> 方式传入，不能拼在 URL 里，也不能用 Basic 认证。示例：
client := cloudflare.NewWithAPIToken("your_token_here")
- Token 必须在 Cloudflare Dashboard → My Profile → API Tokens 页面创建，不要复用旧的 Global API Key
- 测试阶段建议用最小权限 Token，避免误删整个 Zone
- 环境变量中存储 token 时，确保 Go 程序读取后未被意外截断（如换行、空格）
获取 Zone ID 前先确认域名已接入 Cloudflare
调用 client.Zones(context, cloudflare.ZoneListParams{Name: "example.com"}) 返回空列表，不是代码写错了，而是该域名没在 Cloudflare 控制台完成接入（即 NS 记录未切换）。Cloudflare API 不会返回未托管的域名信息，哪怕你拥有该域名的注册权。
Zone ID 是后续所有操作（DNS 修改、防火墙规则、页面规则）的必要参数，无法跳过。正确流程是：
立即学习“go语言免费学习笔记（深入）”；
- 登录 Cloudflare 控制台，确认域名状态为 “Active”（右上角显示橙色云图标）
- 用
client.Zones()查找，注意Name必须完全匹配（不带www.或协议） - 若域名有多个 Zone（如
example.com和api.example.com各自独立托管），需分别查 ID，不能复用
更新 DNS 记录时务必带上现有 record ID，不能仅靠 name+type 匹配
Cloudflare 不支持“按名称和类型原子性更新”，client.CreateDNSRecord() 总是新增，client.UpdateDNSRecord() 必须传入 id。常见错误是先查再更新，但忘了保存查到的 record.ID，导致更新变成 404。
典型安全写法是封装一个 upsertDNSRecord 函数：
records, _ := client.DNSRecords(ctx, zoneID, cloudflare.DNSRecordListParams{Name: "api", Type: "A"})
if len(records) > 0 {
_, err := client.UpdateDNSRecord(ctx, zoneID, records[0].ID, cloudflare.UpdateDNSRecordParams{Content: "192.0.2.1"})
}
- 查询结果可能有多个同名记录（如多条 A 记录做轮询），需根据业务逻辑决定更新哪一条
- Cloudflare 的 TTL 若设为
1（自动），API 返回的record.TTL是1，但实际生效值由系统动态计算，不可依赖其做判断 - 批量更新时，每个
UpdateDNSRecord是独立 HTTP 请求，没有原生批量接口，需自行控制并发数防限流
Rate Limit 触发后响应头含 cf-ray 和 Retry-After，但官方 SDK 不自动重试
Cloudflare 默认每 30 秒最多 1200 次请求（Pro 计划），超限会返回 429 Too Many Requests，响应头带 Retry-After: 1。官方 cloudflare-go 库目前 不内置重试逻辑，也不解析 Retry-After，直接抛错。
生产环境必须自己加兜底：
- 用
github.com/hashicorp/go-retryablehttp替换默认 HTTP client，配置基于状态码和 header 的重试策略 - 对关键操作（如发布防火墙规则）加幂等判断，避免因重试导致重复生效
- 监控日志里重点抓
cf-ray和429，比单纯看错误率更能定位限流源头
真正麻烦的不是写几行重试代码，而是某些操作（比如修改 Page Rule）本身耗时长、成功率不稳定，重试窗口和业务 SLA 往往对不上。这类场景建议改用异步轮询 + webhook 回调，而不是硬扛同步重试。
