A domain-specific exception names a failure in terms the application understands. It prevents a low-level detail such as a parsing failure from leaking unchanged into a business layer, API boundary, or user-facing interface. The visible error can then be meaningful to its recipient, while diagnostic details remain available in logs. section 7.2.4 section 7.1.1
The value is not in elaborate class machinery. An explicitly named exception makes the code read as a story about the domain: invalid order IDs, data-processing problems, and similar conditions are distinct from the technical mechanisms that detected them. Define the exception with the information known when it is created, and keep that information immutable. section 7.2.4
Translate at the boundary
Parsing input may legitimately raise NumberFormatException inside a technical operation. Rather than expose that implementation detail to a higher layer, catch it where the application can assign business meaning and throw DataProcessingException with the input, a useful message, and the original exception as its cause. The same pattern applies when an eight-digit order-ID rule fails: InvalidOrderIdException communicates the violated rule more clearly than NumberFormatException. section 7.2.4
int dataToTransform = 0;
try {
dataToTransform = Integer.parseInt(data);
} catch (NumberFormatException exception) {
throw new DataProcessingException(data, "Processing error", exception);
}
This conversion retains the original cause while replacing a parsing-specific signal with a data-processing failure that callers can understand. section 7.2.4
Choose the translation point deliberately. Action-level code may lack enough context to decide how a failure should be handled, so it can propagate the technical exception to a scene method or higher layer that has the broader picture. Keep protected blocks narrow, avoid generic catches without justification, and do not reveal raw stack traces or sensitive implementation details outside their proper layer. section 7.2.4 section 7.3
Not every anticipated business failure needs an exception. When invalid input is an expected outcome of an operation, model it directly in the contract with explicit result types; a caller can then branch between valid and invalid results. Use a domain-specific exception when the failure path is better expressed as exceptional, and select the strategy that fits the problem rather than applying either pattern mechanically. section 7.2.4 section 7.1.1
A useful translation preserves two audiences:
- Callers receive a meaningful domain exception or controlled response, without raw technical details. section 7.3
- Developers retain the original cause for diagnosis, through exception chaining or immediate logging. section 7.2.4
Use the name as a design test: if it states the application-level condition that failed, it clarifies intent; if it merely repeats a technical mechanism, it may be leaking the wrong abstraction. Translate low-level failures at boundaries, preserve their causes, and expose only the information the recipient needs to act. section 7.2.4 section 7.3
