myxce/.kiro/steering/error-handling.md

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;
}

Controller daemons MUST NEVER self-terminate on an operational condition. A controller exits only on a genuine crash or an admin/supervisor kill — never via exit()/_exit()/abort()/tlog_exit() as a designed response to an operational failure (unrecoverable/corrupt WAL, lost quorum, unreachable peer, failed catch-up). "Fail loud" here means: log a loud operator-visible ERROR (with the actionable boundary), enter a permanent non-promotable/fenced state, stay alive, and keep retrying so the node self-heals when conditions recover — never terminate (a self-exited controller needs manual recovery and degrades quorum meanwhile). assert()/abort is reserved for genuine programming-invariant violations only. Authoritative statement: ha-async-io.md (process-lifecycle invariant) and src/controller/CLAUDE.md ("Process Lifecycle"); precedent: ha-commit-durability's persist_recover_loud_fence_if_unrecoverable + recovery_unrecoverable sticky fence.

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.