Errors

API errors

A complete numeric error-code catalog is not published. Do not invent codes. Use the shapes and status codes actually returned by handlers.

Envelopes #

AUTH_ERR #

Used by AuthHandler and many older c.JSON(..., gin.H{"error": ...}) paths.

{"error": "Invalid credentials"}Copy

Some 2FA login failures add requires_2fa:

{"error": "Two-factor authentication code required", "requires_2fa": true}Copy

V1ERR (`utils.V1ErrorResponse`) #

{
  "success": false,
  "error": "Invalid request format",
  "message": "Invalid request format",
  "code": "BAD_REQUEST"
}Copy

Helper codes from response_helper.go:

Handlers may pass a different code string into RespondError (example: license import PAYLOAD_TOO_LARGE at 413).

V1OK (`utils.V1SuccessResponse`) #

{
  "success": true,
  "message": "license status loaded",
  "data": {}
}Copy

data is omitted when the helper is called with nil.

License 403 (Enterprise) #

licensegate.Gate writes licensing.LicenseErrorResponse on denied entitlement:

{
  "success": false,
  "code": "LICENSE_FEATURE_NOT_ENTITLED",
  "message": "<gate message>",
  "license": {
    "state": "<license state>",
    "edition": "<edition>",
    "feature": null,
    "limit": null,
    "operation": "<operation>",
    "remediation_hint": "<hint>"
  }
}Copy

license is LicenseErrorDetails. Optional fields include sku, channel, required_channel, required_edition, current_usage, allowed_limit. Do not publish SKU names as a customer price list.

Observed bounded codes in Manager metrics (not a complete public catalog): LICENSE_LIMIT_EXCEEDED, LICENSE_FEATURE_NOT_ENTITLED, LICENSE_RESTRICTED_WRITE_DENIED, LICENSE_CLUSTER_JOIN_DENIED, LICENSE_AGENT_REGISTRATION_DENIED, plus updater-channel codes that belong to the in-product updater (not a production upgrade path).

When the license service itself is missing, license routes return 503:

{
  "success": false,
  "error": "license service unavailable",
  "message": "license service unavailable",
  "code": "LICENSE_SERVICE_UNAVAILABLE"
}Copy

Community agent limit 403 #

Community only (Zwall_Community AgentHandler.respondCommunityAgentLimit). Fired on registration-style enroll, web create, and pre-register when CountAgents >= 3.

{
  "success": false,
  "error": "COMMUNITY_AGENT_LIMIT_REACHED",
  "code": "COMMUNITY_AGENT_LIMIT_REACHED",
  "message": "ZWall Community supports up to 3 agents",
  "limit": 3,
  "current_agents": 3
}Copy

Enterprise uses license gates instead of this Community constant.

HTTP status usage (operator) #

SPA / unknown API path #

Missing /api/ routes handled by the Manager SPA fallback return:

{"error": "Endpoint not found", "path": "/api/v1/does-not-exist"}Copy

That is not a V1ERR envelope.

Rate limiting #

• POST /api/v1/auth/login — LoginRateLimiter()
• POST /api/v1/agents/register — RegisterRateLimiter()

Exact 429 JSON is middleware-owned; treat as AUTH_ERR-like or empty body. Do not document bypasses.

Operator troubleshooting #

Related #

• Conventions
• Authentication
• License HTTP APIs are Enterprise-only and are provided separately to Enterprise customers. See Enterprise edition.