Error Handling Standards

Philosophy

Fail fast with a consistent, machine-readable response. Handle errors at the controller boundary; let business logic return typed errors. Never silently swallow errors.

Go API Response Pattern

All HTTP responses go through two helpers in controllers/response.go:

// Success (always HTTP 200)
ReturnSuccess(ctx, common.SUCCESS_CODE, common.SUCCESS_MSG, data)

// Error (HTTP status == code parameter)
ReturnError(ctx, common.ERROR_AUTH_CODE, common.ERROR_ACCESS_FORBIDDEN_MSG, nil)
ctx.Abort()   // always Abort() after ReturnError in middleware
return        // always return immediately after ReturnError in handlers

The early-return pattern is non-negotiable. Every error path ends with ReturnError(...); return.

HTTP Status Code Mapping

Code	Constant	When to use
200	`SUCCESS_CODE`	Successful operation
201	`CREATED`	Resource created
400	`INVALID_PARAMS_CODE`	Malformed or invalid input
401	`ERROR_AUTH_CHECK_TOKEN_CODE`	Missing or invalid JWT
403	`ERROR_AUTH_CODE`	Valid JWT but insufficient permission
404	`ERROR_NOT_FOUND_CODE`	Resource not found
429	`ERROR_TOO_MANY_REQUESTS_CODE`	Rate limit exceeded
500	`ERROR_CODE`	Unexpected server error

All code constants are defined in common/common.go. Add new codes there — do not inline numeric literals in handlers.

Structured Logging with Zap

Log at the call site before returning an error. Use typed field helpers — never fmt.Sprintf in zap calls.

// Preferred pattern
logger.Error("rate limit exceeded",
    zap.String("path", path),
    zap.String("client_ip", ctx.ClientIP()),
    zap.Int("errorcode", code),
)

// For error values
logger.Error("validate token error", zap.Error(err))

// For complex types
logger.Debug("permissions resolved", zap.Any("permsWithType", permsWithType))

Log levels:

Error — operation failed, client or server fault
Warn — recoverable edge case (e.g., retried operation succeeded)
Info — key lifecycle events (server start, config load)
Debug — diagnostic detail, disabled in production

Never log: JWT tokens, passwords, secret keys, or full request bodies containing sensitive data.

C Error Propagation

Return negative errno-style codes for C daemon errors. Use the errnox.h definitions from src/include/xce/. Check and propagate immediately — do not continue on error:

int rc = xce_send_request(&req);
if (rc < 0) {
    log_error("send_request failed: %d", rc);
    return rc;
}

Input Validation Pattern

Validate at the controller boundary using a preCheck{Resource}Request() helper before touching services:

func (c JobController) SubmitJob(ctx *gin.Context) {
    req, err := preCheckSubmitJobRequest(ctx)
    if err != nil {
        ReturnError(ctx, common.INVALID_PARAMS_CODE, err.Error(), nil)
        return
    }
    // ... service call
}

Keep preCheck* functions in the same file as the handler. They bind, validate, and return the typed request struct or an error.

3.1 KiB Raw Blame History