ai-instructions spring-boot-error-code.instructions.md

Spring Boot Error-Code Engine

Naming Conventions

• Name error-code enums or constants with the *ErrorCode suffix (e.g., HolidayErrorCode, PaymentErrorCode).
• Use UPPER_SNAKE_CASE for all error-code enum values (e.g., HOLIDAY_NOT_FOUND, DUPLICATE_HOLIDAY).
• Include the resource or domain name as a prefix in every error code value to prevent ambiguity across modules (e.g., USER_NOT_FOUND, not NOT_FOUND).
• Use domain-specific error-code catalog names (never AppErrorCode, CommonErrorCode, or GeneralErrorCode).

Rules

• Keep error codes stable after public release.
• Keep message keys separate from error codes.
• Map each error code to exactly one failure scenario.
• When adding a new failure path, declare the error code constant in the *ErrorCode enum before writing any code that references it.
• Resolve HTTP status codes in the exception handler layer.
• Use one canonical error-code strategy per module: either a dedicated *ErrorCode catalog or handler-local constants, but not both.
• Use a dedicated *ErrorCode catalog when error-code values are shared across multiple exception types or handlers in the same module.
• Use handler-local constants only when error-code ownership is isolated to a single handler.
• Declare error codes only in dedicated catalog classes or handler-local constants.
• Keep machine-readable error-code fields explicit only for modules whose public error payload contract exposes an errorCode property.
• When the errorCode field is exposed in the API payload, format its value as the UPPER_SNAKE_CASE enum constant name.
• Scope each *ErrorCode catalog to a single feature.
• Create a module-level error code catalog (e.g., ApiErrorCode) in shared for HTTP-framework failures that are not owned by any feature, such as unmapped routes, request validation, and unexpected server errors.
• Create separate *ErrorCode catalogs per feature when a module has multiple resources with distinct failure domains.
• When retiring an error code, annotate it @Deprecated, keep it active for at least one major version, and document the replacement code in the deprecation annotation.