magnus919_agent-skills/backend-engineering/references/error-handling.md

Error Handling

Error Classification

Category	HTTP analogue	What it means	Example
Validation	400	The client sent something wrong	Missing required field
AuthN/AuthZ	401/403	The caller can't do this	Expired token, insufficient permissions
Not Found	404	The resource doesn't exist	Invalid ID, deleted entity
Conflict	409	The operation can't complete due to state	Duplicate, stale version
Rate Limited	429	Too many requests	Quota exceeded
Internal	500	Something went wrong on the server	DB down, unhandled exception
Unavailable	503	The service can't handle the request right now	Circuit open, overloaded

Exception Handling Strategy

Catch location	What to do	Example
Repository	Wrap DB errors in domain exceptions	UserNotFoundException, DuplicateEmailError
Service	Handle domain exceptions, orchestrate recovery	Retry on conflict, fallback on unavailable
Controller boundary	Map domain exceptions to error responses	UserNotFoundException → 404 with error body
Middleware boundary	Catch unhandled exceptions, log, return 500	Global error handler, structured log + trace

Structured Logging Fields

Every log entry at service level should include:

• request_id — correlation ID from request header or generated at middleware
• service — service name
• operation — what operation was being performed
• duration_ms — how long it took
• error_code — if error, machine-readable code
• caller — function/module that produced the log

Error Response Body

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after the specified time.",
    "retry_after_seconds": 30,
    "request_id": "req_abc123"
  }
}