Error Codes

Standardized API error semantics and recommended status mapping.

Response envelope

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "statusCode": 400
  }
}

Core error catalog

CodeStatusTypical trigger
UNAUTHORIZED401Missing auth session
FORBIDDEN403Access outside member/role scope
VALIDATION_ERROR400Zod schema mismatch
NOT_FOUND404Resource missing by id/code
GROUP_FULL400Join request exceeds maxMembers
ALREADY_MEMBER409Duplicate group membership
INVALID_JOIN_CODE404Join code lookup miss
CONFLICT409Resource state conflict
INTERNAL_ERROR500Unhandled server exception

Design guidelines

  • Keep code stable for frontend branching and telemetry.
  • Use message for user-facing fallback copy.
  • Include field-level validation details for VALIDATION_ERROR when available.