错误码总览

业务码 = 0 表示成功；非 0 由各模块自定义。所有错误响应 HTTP 体形如：
{ "code": <业务码>, "message": "<人读消息>" }

本页列出 Cloud WAF 平台全部业务错误码（与 pkg/errors/codes.go 真值源一一对账）。第三方接入方应该按 code 分支决策，不要解析 message 文本——文本随多语言/版本可能变化。

HTTP 状态码 vs 业务错误码

平台两层错误模型：

约定：

• 业务码 = 0 时 HTTP 必为 200。
• 业务码 ≠ 0 时 HTTP 一般 4xx/5xx，但少数幂等接口（如重复吊销 API Key）即使业务码非 0 也返回 200。
• HTTP 401（凭据失效）特意合并多种"未通过认证"成单一返回，避免侧信道暴露内部状态——业务层不再细分。
• HTTP 403（凭据有效但权限不足）会带具体业务码（1011 / 1052 / 1053 / 1056 等），客户端按业务码区分处置。

通用 HTTP 错误码（非业务码）

仅在请求未到达业务逻辑时返回（参数校验失败、协议错误、未授权）。

模块码段分配

sys 模块（1000–1999）

用户与认证（1001–1011）

设置与 OEM（1012, 1020–1023）

订单与套餐（1030–1033, 1040）

API Key 子模块（1050–1059）

scope 匹配规则：精确字符串相等，不展开通配符（写 guard.* 进 scope 不会匹配任何接口）。需要某模块全部权限时请逐条列叶子 perm key。

guard 模块（2000–2999）

域名与策略（2001–2010）

IP 集与规则（2011–2019）

node 模块（3000–3999）

chart 模块（4000–4999）

alert 模块（5000–5999）

zdns 模块（6000–6999）

notify 模块（7000–7999）

report 模块（8000–8999）

assistant 模块（9000–9999）

geoip 模块（10000–10999）

channel 模块（11000–11999）

跨模块通用约定

• HTTP 401 → 凭据失效（统一码，故意合并避免侧信道）
• HTTP 403 → 凭据有效但权限/归属不匹配，业务码用于细分（1011 / 1052 / 1053 / 1056 / 1009 / 1022 / 2017 / 3010 等）
• HTTP 404 → 资源不存在或不在可见范围（典型业务码 1001 / 1020 / 2001 / 3001 …）
• HTTP 409 → 唯一性冲突（典型业务码 1006 / 1021 / 2002 / 3002 …）
• HTTP 429 → 限流，带 Retry-After 头（4005 / 5008 / 5009）
• HTTP 5xx → 服务端故障，建议指数退避重试（10ms → 100ms → 1s → 10s）

客户端处置建议

# Python 伪代码：基于业务码而非 HTTP 状态决策
import requests
from time import sleep

resp = requests.get(api_url, headers={"Authorization": f"ApiKey {key}"})
body = resp.json()
code = body.get("code", -1)

if code == 0:
    return body["data"]
elif code == 1050:
    raise Exception("API Key 失效，请重新签发")
elif code == 1052:
    raise Exception(f"scope 越权：{body['message']}")
elif code in (4005, 5008, 5009):
    sleep(int(resp.headers.get("Retry-After", "60")))
    return retry()
elif code >= 5000 and resp.status_code >= 500:
    return exponential_backoff_retry()
else:
    raise Exception(f"业务错误 {code}: {body['message']}")

永远基于 code 字段决策，不要解析 message 文本——文本随多语言/版本变化。