[Feature] Standardize HTTP API Error Messages

Summary

Some HTTP APIs return Java exception class names and unaudited Throwable.getMessage() values to clients when handling exceptions, for example:

{
  "Error": "class java.lang.NullPointerException : null"
}

This proposal standardizes client-facing error messages from standard HTTP Servlets in phase 1:

• Existing messages are temporarily preserved for exceptions explicitly covered for compatibility.
• All other exceptions return the stable message internal server error.
• Java exception class prefixes and raw exception messages that are not explicitly allowed are no longer returned to clients.

Phase 1 changes only the content and format of failure responses. Successful responses, request rules, HTTP status codes, and gRPC behavior remain unchanged.

The shared HTTP rate-limit response is also sanitized for JSON-RPC endpoints, returning {"Error":"lack of computing resources"} without the Java exception class prefix. Other JSON-RPC behavior remains unchanged.

Problem

Motivation

Returning runtime exception information directly to clients has the following problems:

• It provides little value to clients in diagnosing or handling request failures.
• Exception messages may change with JDK or dependency versions and are unsuitable as a stable, long-term API contract.

Current State

Before this change, standard HTTP error-response paths behave inconsistently:

• Util.processError returns a concatenation of the Java exception class name and raw message.
• Some Servlets bypass Util.processError and directly return exception class names or Throwable.getMessage() values.
• Two Solidity query endpoints return plain-text error bodies instead of standard JSON.

Limitations and Risks

• Clients that depend on Java exception class names, raw exception messages, or plain-text error bodies will observe compatibility changes.
• To limit the compatibility impact of phase 1, non-blank raw messages from three exact exception types are temporarily preserved.

Proposed Solution

Proposed Design

1. Standardize HTTP error-response paths

The standard Servlet JSON and text error-response paths governed by phase 1 are routed through Util.processError, which centrally determines the final client-facing message.

Endpoints with a specialized response format, such as validateaddress, retain that format and replace dynamic exception messages locally.

2. Preserve compatibility messages for three exact exception types

For compatibility with existing clients, exception classification preserves raw messages only for the following exact runtime types:

• JsonFormat.ParseException
• ContractValidateException
• MaintenanceUnavailableException

These three cases are legacy residuals temporarily retained for compatibility with existing behavior. Subclasses and nested causes are not matched.

3. Preserve audited fixed and existing response texts

Existing client-facing validation and state messages are preserved through their audited paths:

• The rate limiter directly returns the fixed text lack of computing resources, without constructing an exception for formatting.
• The Scan Events deprecation text is preserved only when both the exact IllegalArgumentException type and EVENTS_DEPRECATED_MSG match.
• Existing GetBlock validation messages and fixed address-validation responses are retained.

These fixed or pre-existing response texts do not broaden the exception-type compatibility rules above.

4. Fail closed for all other exceptions

Except for the explicitly allowed compatibility branches above, exceptions must not expose Java exception class names or raw messages to clients. This includes, but is not limited to:

• NullPointerException
• Array or collection bounds exceptions
• Ordinary IllegalArgumentException
• Other unmapped runtime or internal exceptions

They return:

{
  "Error": "internal server error"
}

Key Changes

• The change is limited to the HTTP Servlet layer in the framework module.
• Standard JSON and text error-response paths governed by phase 1 are routed through Util.processError.
• Java exception class prefixes are removed from standard error responses.
• Exception compatibility rules use exact runtime types and, for the events-deprecation exception, an exact message constant.
• Exceptions that are not explicitly allowed return internal server error.
• The two Solidity query endpoints change their error bodies from plain text to standard {"Error":"..."} JSON.
• The shared rate-limit response is sanitized for all affected HTTP endpoints, including JSON-RPC endpoints.

Impact

• Security
  • Standard generic and unclassified error-response paths no longer return Java exception class names or uncontrolled raw messages.
  • The three compatibility branches that retain raw messages remain known residuals.
• Stability
  • Unknown exceptions use a stable message instead of depending on JDK or library exception messages.
• Performance
  • The change adds only lightweight exception-type and fixed-message comparisons.
  • Normal request paths are unaffected.
• Developer Experience
  • Standard HTTP error-response behavior is centralized in Util.processError.

Compatibility

Item	Result
Breaking Change	Yes, limited to some HTTP failure responses. Some error messages will change, including the shared rate-limit response used by JSON-RPC endpoints. The two Solidity query endpoints will return JSON instead of plain-text error bodies. These changes must be included in the release notes.
Default Behavior Change	Yes. Only failure responses change; successful responses remain unchanged.
Migration Required	Conditional. Clients that rely only on successful responses or documented response fields require no migration. Clients that depend on Java exception class names, raw exception messages, or plain-text Solidity error bodies must be updated.

Affected clients should:

• Read the Error field from the standard JSON response.
• Stop depending on Java exception class names.
• Stop treating JDK or third-party exception messages as a stable API contract.
• Handle unknown server errors as internal server error.

The following behavior remains unchanged:

• Existing HTTP status codes
• Status codes and response content for successful requests
• Request parameters and validation rules
• gRPC API behavior
• JSON-RPC behavior, except for the shared HTTP rate-limit response described above

Acceptance Criteria

• Standard Servlet error-response paths governed by phase 1 generate responses through Util.processError; endpoints with specialized response formats retain their formats and use audited messages.
• These paths no longer concatenate Java exception class names or directly return arbitrary Throwable.getMessage() values.
• On the exception-classification path, only the exact runtime types JsonFormat.ParseException, ContractValidateException, and MaintenanceUnavailableException may preserve non-blank raw messages.
• For those three types, a null, empty, or whitespace-only message results in internal server error.
• Subclasses and nested causes do not inherit compatibility exemptions.
• The events-deprecation message is preserved only when both the exact exception type and exact message constant match.
• Rate-limit rejections return {"Error":"lack of computing resources"}, including on JSON-RPC endpoints.
• Existing audited GetBlock validation messages and fixed address-validation responses are preserved.
• All other exceptions return:

{
  "Error": "internal server error"
}

• If writing the error response to the client fails, at most one additional debug log entry is recorded.
• The two Solidity query endpoints return standard JSON error responses.
• HTTP status codes, successful responses, request rules, and gRPC behavior remain unchanged.
• JSON-RPC behavior remains unchanged except for the shared HTTP rate-limit response described above.

Follow-up

Future phases will:

• Distinguish client parameter errors from internal server errors based on the specific HTTP input source.
• Avoid treating JDK or third-party exception messages as part of the long-term API contract.

Additional Notes

• Do you have ideas regarding implementation? Yes. Route the in-scope standard Servlet error paths through Util.processError, classify exceptions by exact runtime type, and preserve audited fixed or existing response texts at their designated call sites.
• Are you willing to implement this feature? Yes.

Start in the framework module by reading Util.processError and tracing the standard Servlet error paths named in the issue. Then inspect the rate-limit, validateaddress, GetBlock, events-deprecation, and two Solidity query endpoint paths. Done means audited responses follow the stated exact-type rules, unknown exceptions return internal server error, and successful behavior remains unchanged.