# Description of Changes
Implemented RFC 7807 problem-details standard to provide consistent,
structured error responses across the application. All exceptions now
flow through a centralized `GlobalExceptionHandler` with tailored
handlers for password-protected files, corruption, validation, and
Spring framework errors. Every response includes localized `errorCode`,
contextual hints, actionable guidance, timestamps, and request paths.
**Key improvements:**
- Unified error handling prevents inconsistent response formats across
services
- Localized error messages support multiple languages at runtime
- Error context (hints, actionRequired field) improves user experience
- Structured metadata enables programmatic error handling on client side
Reference:
https://www.baeldung.com/spring-boot-return-errors-problemdetail
### Exception Handling
- Centralized all exception handling in `GlobalExceptionHandler` with
specific handlers for password protection, file corruption, validation
errors, and Spring exceptions
- Refactored `ExceptionUtils` to generate consistent `ProblemDetail`
responses with error metadata
- Introduced `ErrorCode` enum to centralize error identification and
metadata (supports localization)
- Added helper methods for creating standardized exceptions across
services
### Implementation Details
- **Replaced generic exceptions** with `ExceptionUtils` methods across
utility classes (`CbrUtils`, `CbzUtils`, `PdfToCbrUtils`,
`EmlProcessingUtils`, `ImageProcessingUtils`) for consistent error
handling of invalid formats, empty files, and missing resources
- **Improved method signatures** in `JobExecutorService` and
`AutoJobAspect` by explicitly declaring thrown exceptions
- **Refined job execution error handling** by removing unnecessary catch
blocks in synchronous execution, allowing exceptions to propagate to the
centralized handler
- **Enhanced error messages** for unsupported formats (e.g., RAR5
limitations, PDF-to-CBR constraints) with clearer user guidance
### Response Format
All errors now include:
- `errorCode`: Machine-readable error identifier (localized at runtime)
- `title`: Localized error title
- `detail`: Context-specific error message
- `hints`: Array of actionable suggestions
- `actionRequired`: Boolean flag indicating if user action is needed
- `timestamp`: Error occurrence time
- `path`: Request path where error occurred
**Error examples shown in PR include:** corrupt files, invalid
passwords, unsupported formats (RAR5), missing images, OOM conditions,
and invalid HTML
### Why This Change
- Eliminates ad-hoc error handling patterns scattered across services
- Provides actionable guidance instead of technical stack traces
- Supports error messages in multiple languages without code changes
- Aligns with RFC 7807, improving API interoperability
- Error context reduces time to diagnose issues
### Error sample (note the unformatted JSON is NOT visible by default
but for presenting purposes I clicked on show stack on each error. By
default only error banner (top part of error) visible)
Corrupt file:
<img width="1912" height="568" alt="image"
src="https://github.com/user-attachments/assets/fc6c9dd6-4929-49ab-8e44-bd79c59d875a"
/>
Password-protected file (invalid password):
<img width="1912" height="757" alt="image"
src="https://github.com/user-attachments/assets/31632271-8b2f-45c5-ad4a-dff51e085ea0"
/>
Unsupported RAR:
<img width="1912" height="636" alt="image"
src="https://github.com/user-attachments/assets/d13cd521-4b07-4399-b97b-4defa842fc05"
/>
No images in RAR/ZIP:
<img width="1912" height="642" alt="image"
src="https://github.com/user-attachments/assets/f02999ed-7a56-4e34-9a95-df50c77012cf"
/>
OOM:
<img width="1912" height="714" alt="image"
src="https://github.com/user-attachments/assets/3aaf491a-fe42-4831-b905-a4d248e34860"
/>
Invalid html (on the html to pdf endpoint)
<img width="1912" height="577" alt="image"
src="https://github.com/user-attachments/assets/584ec7c8-f14c-4eb1-a6b2-cf7812ae8f0a"
/>
GS conversion fail:
<img width="1912" height="674" alt="image"
src="https://github.com/user-attachments/assets/8504a876-75e6-40ef-891b-4ee2b3bbdb0a"
/>
<!--
Please provide a summary of the changes, including:
- What was changed
- Why the change was made
- Any challenges encountered
Closes #(issue_number)
-->
---
## Checklist
### General
- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings
### Documentation
- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)
### UI Changes (if applicable)
- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)
### Testing (if applicable)
- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.
---------
Signed-off-by: Balázs Szücs <bszucs1209@gmail.com>
