Error Code Reference

Business code = 0 means success; non-zero codes are module-specific. Every error response uses:
{ "code": <business_code>, "message": "<human readable>" }

This page lists all business error codes returned by Cloud WAF (mirroring pkg/errors/codes.go as the source of truth). Third-party integrators should branch on code and must not parse message text — the text is i18n / version dependent.

HTTP status vs business code

The platform uses a two-layer error model:

Conventions:

• code = 0 always implies HTTP 200.
• code != 0 usually maps to HTTP 4xx / 5xx, but a few idempotent endpoints (e.g. revoking an already-revoked API key) return HTTP 200 with a non-zero code.
• HTTP 401 (credential invalid) deliberately collapses every "not authenticated" cause into one response to avoid side-channel leakage.
• HTTP 403 (authenticated but unauthorized) carries a specific business code (1011 / 1052 / 1053 / 1056 …) for client-side disambiguation.

Common HTTP errors (not business codes)

Returned when a request never reaches business logic (validation, protocol, auth).

Module code ranges

sys module (1000–1999)

Users & authentication (1001–1011)

Settings & OEM (1012, 1020–1023)

Orders & plans (1030–1033, 1040)

API Key sub-module (1050–1059)

Scope matching: exact string equality, no wildcard expansion. Putting guard.* into a scope matches nothing — list all leaf perm keys explicitly when you want full module access.

guard module (2000–2999)

Domains & policies (2001–2010)

IP sets & rules (2011–2019)

node module (3000–3999)

chart module (4000–4999)

alert module (5000–5999)

zdns module (6000–6999)

notify module (7000–7999)

report module (8000–8999)

assistant module (9000–9999)

geoip module (10000–10999)

channel module (11000–11999)

Cross-module conventions

• HTTP 401 → credential invalid (single code by design, no side-channel leak)
• HTTP 403 → authenticated but lacks ownership / permission; business code disambiguates (1011 / 1052 / 1053 / 1056 / 1009 / 1022 / 2017 / 3010 …)
• HTTP 404 → resource not found or out of visible scope (e.g. 1001 / 1020 / 2001 / 3001 …)
• HTTP 409 → uniqueness conflict (e.g. 1006 / 1021 / 2002 / 3002 …)
• HTTP 429 → rate limited, includes Retry-After header (4005 / 5008 / 5009)
• HTTP 5xx → server-side fault, recommend exponential backoff (10ms → 100ms → 1s → 10s)

Client handling pattern

# Python pseudo-code: branch on business code, not HTTP status
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 invalid, please re-issue")
elif code == 1052:
    raise Exception(f"scope exceeded: {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"business error {code}: {body['message']}")

Always branch on code. Never parse message text — it changes with i18n and version.