I think the current implementation does not actually establish one unified runtime path yet. It adds new mappers/advice, but several existing paths either bypass them or now compete with them.

Current shape:

Expected:
 server / pd / store
 -> one clear response contract
Current PR:
 server -> old ExceptionFilter + new mapper providers coexist
 pd -> many controller-level catch blocks still return old RestApiResponse
 store -> HgStoreException business code is replaced by generic HTTP 400/500 in the body

The main design issues are:

1. PD exceptions are often caught before @RestControllerAdvice can see them. Many PD REST APIs already catch PDException and directly return RestApiResponse or the existing toJSON(e) format, so a new PDExceptionMapper only covers exceptions that escape the controller.

PD controller
 -> catch PDException
 -> return old RestApiResponse / old JSON
 -> new advice is bypassed

2. Server now has two competing Jersey exception-mapping paths. The server module already has ExceptionFilter with mappers for HugeException, IllegalArgumentException, NotFoundException, NoSuchElementException, WebApplicationException, HugeGremlinException, and unknown exceptions. This PR adds another provider package under org.apache.hugegraph.api, which is scanned by ApplicationConfig.

ApplicationConfig packages("org.apache.hugegraph.api")
 -> existing ExceptionFilter.*Mapper
 -> new exceptionshandler.*Mapper

That makes the effective behavior unclear. If the new HugeExceptionMapper wins, it also maps most HugeException cases to HTTP 400 by default, which can incorrectly classify server-side failures as client errors.

3. Store loses the original HgStoreException business code. HgStoreException has useful domain codes such as 1001, 1201, 1202, 1208, 1401, etc. But the new StoreExceptionHandler returns status.value() as the response code, so clients only see generic 400 or 500 instead of the actionable store error code.

Before:
 HgStoreException code = 1202
After this PR:
 response.code = 500

I suggest first defining the response contract and then updating the existing runtime paths instead of adding parallel ones:

PD:
 handle existing catch-and-return paths, or migrate/normalize RestApiResponse
Server:
 modify the existing ExceptionFilter path instead of adding competing mappers
Store:
 keep HgStoreException business code while using HTTP status for transport semantics
Tests:
 add REST-level tests that prove actual endpoints return the unified format

One unrelated item: hugegraph-pd/hg-pd-service/pom.xml adds <classifier>exec</classifier>, which changes the PD packaging output and does not seem related to REST response unification. Please split it out or explain why it is required here.

A larger concern is that this PR changes the public REST API response contract. The server / pd / store REST APIs may already be consumed by external services, so a large response-format change can have significant downstream impact.

Current response shapes include fields such as:

server errors:
 exception / message / cause / trace
pd responses:
 message / data / status
 or status / error
store errors:
 module-specific business error codes

The new envelope introduces a different shape:

ApiResponse:
 code / message / data / status

That can break clients that parse existing fields like exception, error, status, or store-specific business codes. Even if the new format is cleaner, this kind of API contract change should be designed and discussed carefully before implementation.

I think we should first decide the compatibility and migration strategy, for example:

Questions to settle before implementation:
 - Is this intended to be a breaking public API response change?
 - If not, how do old clients keep receiving the old format?
 - Should the unified format be opt-in through a version/header/parameter?
 - Is there a deprecation period with compatibility fields?
 - Should normal responses also be wrapped, or only error responses?
 - Is `code` the HTTP status or the business error code?
 - What should be documented in REST docs / OpenAPI / release notes?

If this is intended to be a breaking change, it should probably go through community discussion and come with docs, migration notes, OpenAPI updates, and REST-level compatibility tests. If it is not intended to be breaking, then the implementation needs an explicit compatibility layer rather than replacing existing response bodies directly.

In short:

First:
 define API contract + compatibility/migration plan
Then:
 implement the unified response format against that contract

Hi @imbajin,
Thank you for the detailed review. You raised several important concerns regarding runtime consistency, exception flow coverage, and backward compatibility of the public REST API contract.
I agree that the current approach still leaves multiple competing exception-handling paths in place instead of establishing a single unified runtime contract.
The points you raised are all valid and need to be addressed before this can be considered a proper unification.
My current thinking is:

Server: integrate the unified formatting into the existing ExceptionFilter infrastructure.
PD: explore consolidating the existing controller-level catch-and-return patterns so exceptions can follow a consistent handling path.
Store: preserve existing HgStoreException business codes in the response body while keeping HTTP status codes strictly for transport semantics.
I also agree that the larger concern here is API compatibility. Since the current REST responses already expose module-specific response shapes and fields, introducing a new envelope format without a migration strategy could break downstream consumers.
Before continuing implementation, I think we should first align on:

• the target error response contract,
• compatibility expectations,
• migration/deprecation strategy,
• and whether this should be treated as a breaking API change.

Do you think it would be better to continue this discussion in the PR thread, or would this be more appropriate for a broader dev mailing list discussion first?
Thanks again for the thoughtful review — this was very helpful in clarifying the architectural direction the PR should take.

EDIT:
About the hugegraph-pd/hg-pd-service/pom.xml adding <classifier>exec</classifier> I added the <classifier>exec</classifier> during my local testing phase to resolve a multi-module classpath visibility issue where other modules couldn't properly locate classes packed inside the Spring Boot layout during test compilation.
Since this impacts the core packaging behavior and is indeed unrelated to the REST response unification contract, I will remove it from this PR, thanks for pointing that out.

IMO, a controller should only be responsible for receiving external requests and returning responses — exception handling logic does not belong there. We should remove the catch blocks from controllers and let a centralized handler take care of error formatting.

For the store business code, rather than replacing it with the HTTP status code, we could simply add a dedicated field (e.g. storeBizCode) to the response envelope to carry the original HgStoreException code alongside the HTTP status. That way transport semantics and domain error codes stay cleanly separated without losing any information.

That said, it's worth classifying controllers by their audience — user-facing, admin-facing, or internal module-facing. Internal module-facing interfaces may reasonably keep their existing response format unchanged, while the unified response format should at minimum be enforced across all user-facing endpoints.

On compatibility: could we treat this as a breaking change and land it in the next major/minor version with proper release notes and migration guidance?
cc @imbajin