hiero-ledger / hiero-ledger/hiero-enterprise-java
[Refactor] Improve error handling with a structured exception hierarchy
- Dominant language
- Java
- Stars
- 6
- Forks
- 21
- Avg merge
- 10h 27m
- Merged PRs (30d)
- 37
Description
## Problem
I’ve been working through the error handling in hiero-enterprise-base lately, and I noticed that almost every failure eventually gets swallowed up by a generic HieroException.
While that keeps things simple, it’s a bit of a headache for the end-user. If I want my app to behave differently for a "Payer Balance" issue versus a Network Timeout or a Signing Error, I currently have to resort to string-parsing exception messages. As we all know, that’s pretty fragile and breaks easily.
## The Idea
I’d like to introduce a more structured exception hierarchy. The goal isn't to over-complicate things, but to give developers a way to catch specific types of failures without losing the common HieroBaseException type.
I'm thinking of something like this:
- HieroProtocolException: Specifically for Hedera-specific status codes (like INSUFFICIENT_PAYER_BALANCE).
- HieroSecurityException: For when things go wrong with signing or keys.
- HieroConfigurationException: For missing providers or setup issues.
- HieroValidationException: For pre-check and request validation failures.
## Why this helps
This would make it way easier to implement clean retry logic or custom alerting on the application side. It moves the library toward being more enterprise-friendly by providing actionable errors instead of just a generic something went wrong message.
Contributor guide
Research direction
Start by locating HieroException and tracing how failures from status codes, signing or keys, configuration, and validation currently reach it. Define the exception relationships and mappings before changing callers. Done means developers can catch the proposed specific types while retaining a common HieroBaseException type, with existing failure behavior preserved.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100