[QoS][JSONRPC] Generic error responses use JSONRPC error codes not in the reserved ranges (#454)

## Summary

Standardize JSON-RPC error codes across the codebase by introducing
dedicated constants and distinguishing between internal PATH errors and
backend server errors

### Primary Changes:

- Add new ResponseCodeBackendServerErr (-31002) constant to distinguish
backend server errors from internal PATH errors
- Update ResponseCodeDefaultInternalErr from -32000 to -31001 to use
non-reserved JSON-RPC error codes
- Replace hardcoded -32000 error codes throughout codebase with
appropriate named constants

### Secondary Changes:

- Update comments to reference new constant names and provide clearer
error code documentation
- Add TODO comment in evm/errors.go considering further error code
granularity

## Issue

Need to distinguish PATH generated JSONRPC error codes from
endpoint/backend server JSONRPC error responses.

- Issue or PR: #{ISSUE_OR_PR_NUMBER}

## Type of change

Select one or more from the following:

- [x] New feature, functionality or library
- [ ] Bug fix
- [ ] Code health or cleanup
- [ ] Documentation
- [ ] Other (specify)

## QoS Checklist

### E2E Validation & Tests

- [ ] `make path_up`
- [ ] `make test_e2e_evm_shannon`

### Observability

- [ ] 1. `make path_up`
- [ ] 2. Run the following E2E test: `make
test_request__shannon_relay_util_100`
- [ ] 3. View results in LocalNet's [PATH Relay Grafana
Dashboard](http://localhost:3003/d/relays/path-service-requests)

## Sanity Checklist

- [x] I have updated the GitHub Issue `assignees`, `reviewers`,
`labels`, `project`, `iteration` and `milestone`
- [ ] For docs, I have run `make docusaurus_start`
- [ ] For code, I have run `make test_all`
- [ ] For configurations, I have updated the documentation
- [x] I added `TODO`s where applicable

Author: adshmh

qos/cosmos/response_jsonrpc.go

@@ -13,9 +13,9 @@ import (
 
 const (
 	// error codes to use as the JSONRPC response's error code if the endpoint returns a malformed response.
-	// -32000 Error code will result in returning a 500 HTTP Status Code to the client.
-	errCodeUnmarshaling  = -32000
-	errCodeEmptyResponse = -32000
+	// `jsonrpc.ResponseCodeBackendServerErr`, i.e. code -31002, will result in returning a 500 HTTP Status Code to the client.
+	errCodeUnmarshaling  = jsonrpc.ResponseCodeBackendServerErr
+	errCodeEmptyResponse = jsonrpc.ResponseCodeBackendServerErr
 
 	// Error messages for JSONRPC response validation failures
 	errMsgJSONRPCUnmarshaling  = "the JSONRPC response returned by the endpoint is not valid"

qos/evm/errors.go

@@ -6,12 +6,14 @@ import (
 	"github.com/buildwithgrove/path/qos/jsonrpc"
 )
 
+// TODO_CONSIDERATION(@adshmh): Is there any value in further breaking down error codes here to indicate different failures?
+//
 // newErrResponseInternalErr creates a JSON-RPC error response when an internal error has occurred (e.g. reading HTTP request's body)
 // Marks the error as retryable to allow clients to safely retry their request.
 func newErrResponseInternalErr(requestID jsonrpc.ID, err error) jsonrpc.Response {
 	return jsonrpc.GetErrorResponse(
 		requestID,
-		-32000, // JSON-RPC standard server error code; https://www.jsonrpc.org/historical/json-rpc-2-0.html
+		jsonrpc.ResponseCodeDefaultInternalErr,         // Used to indicate an internal error on PATH/protocol (e.g. failed to read the HTTP request's body)
 		fmt.Sprintf("internal error: %s", err.Error()), // Error Message
 		map[string]string{
 			"error": err.Error(),
@@ -32,8 +34,8 @@ func newErrResponseInternalErr(requestID jsonrpc.ID, err error) jsonrpc.Response
 // The error is marked as permanent since retrying without correcting the request will fail.
 func newErrResponseInvalidRequest(err error, requestID jsonrpc.ID) jsonrpc.Response {
 	return jsonrpc.GetErrorResponse(
-		requestID, // Use request's original ID if present
-		-32000,    // JSON-RPC standard server error code; https://www.jsonrpc.org/historical/json-rpc-2-0.html
+		requestID,                             // Use request's original ID if present
+		jsonrpc.ResponseCodeDefaultBadRequest, // JSON-RPC error code indicating bad user request
 		fmt.Sprintf("invalid request: %s", err.Error()), // Error Message
 		map[string]string{
 			"error": err.Error(),

qos/evm/response_generic.go

@@ -12,8 +12,8 @@ import (
 
 const (
 	// errCodeUnmarshaling is set as the JSONRPC response's error code if the endpoint returns a malformed response.
-	// -32000 Error code will result in returning a 500 HTTP Status Code to the client.
-	errCodeUnmarshaling = -32000
+	// `jsonrpc.ResponseCodeBackendServerErr`, i.e. code -31002, will result in returning a 500 HTTP Status Code to the client.
+	errCodeUnmarshaling = jsonrpc.ResponseCodeBackendServerErr
 
 	// errMsgUnmarshaling is the generic message returned to the user if the endpoint returns a malformed response.
 	errMsgUnmarshaling = "the response returned by the endpoint is not a valid JSONRPC response"

qos/jsonrpc/errors.go

@@ -5,8 +5,15 @@ import (
 )
 
 const (
-	ResponseCodeDefaultInternalErr = -32000 // JSON-RPC standard server error code; https://www.org/historical/json-rpc-2-0.html
-	ResponseCodeDefaultBadRequest  = -32600 // JSON-RPC error code indicating bad user request
+	// DEV_NOTE: Intentionallly using Non-reserved JSONRPC error code for internal errors.
+	// Allows distinguishing errors coming from PATH from backend server errors.
+	// e.g.
+	// -32000: indicates a backend server (ETH, Solana, etc.) returned the error.
+	// -31001: indicates PATH consturcted the JSONRPC error response (e.g. if the endpoint payload failed to parse as a JSONRPC response)
+	ResponseCodeDefaultInternalErr = -31001 // JSON-RPC server error code; https://www.jsonrpc.org/specification#error_object
+	ResponseCodeBackendServerErr   = -31002 // Indicates a backend server error: e.g. payload could not be parsed into a valid JSON-RPC response.
+
+	ResponseCodeDefaultBadRequest = -32600 // JSON-RPC error code indicating bad user request
 )
 
 // NewErrResponseInternalErr creates a JSON-RPC error response when an internal error has occurred (e.g. reading HTTP request's body)
@@ -52,8 +59,8 @@ func NewErrResponseInvalidRequest(requestID ID, err error) Response {
 //   - Marks error as retryable for safe client retry
 func NewErrResponseEmptyEndpointResponse(requestID ID) Response {
 	return GetErrorResponse(
-		requestID, // Use request's original ID if present
-		-32000,    // JSON-RPC standard server error code; https://www.jsonrpc.org/historical/json-rpc-2-0.html
+		requestID,                    // Use request's original ID if present
+		ResponseCodeBackendServerErr, // Indicates a backend server error caught by PATH.
 		"Endpoint (data/service node error): Received an empty response. The endpoint will be dropped from the selection pool. Please try again.", // Error Response Message
 		map[string]string{
 			// Custom extension - not part of the official JSON-RPC spec
@@ -71,8 +78,8 @@ func NewErrResponseEmptyEndpointResponse(requestID ID) Response {
 //   - Provides actionable message for clients
 func NewErrResponseNoEndpointResponse(requestID ID) Response {
 	return GetErrorResponse(
-		requestID, // Use request's original ID if present
-		-32000,    // JSON-RPC standard server error code; https://www.jsonrpc.org/historical/json-rpc-2-0.html
+		requestID,                      // Use request's original ID if present
+		ResponseCodeDefaultInternalErr, // Used to indicate an internal PATH/protocol error (e.g. endpoint timed out).
 		"Failed to receive any response from endpoints. This could be due to network issues or high load. Please try again.", // Error Response Message
 		map[string]string{
 			// Custom extension - not part of the official JSON-RPC spec
@@ -87,8 +94,8 @@ func NewErrResponseNoEndpointResponse(requestID ID) Response {
 // Uses null ID per JSON-RPC spec for batch-level errors that cannot be correlated to specific requests.
 func NewErrResponseBatchMarshalFailure(err error) Response {
 	return GetErrorResponse(
-		ID{},   // Use null ID for batch-level failures per JSON-RPC spec
-		-32000, // JSON-RPC standard server error code; https://www.jsonrpc.org/historical/json-rpc-2-0.html
+		ID{},                           // Use null ID for batch-level failures per JSON-RPC spec
+		ResponseCodeDefaultInternalErr, // Used to indicate an internal PATH/protocol error: here it indicates failure to marshal a batch JSON-RPC response.
 		fmt.Sprintf("Failed to marshal batch response: %s", err.Error()), // Error Message
 		map[string]string{
 			"error": err.Error(),

qos/solana/response_generic.go

@@ -15,8 +15,8 @@ import (
 
 const (
 	// errCodeUnmarshaling is set as the JSON-RPC response's error code if the endpoint returns a malformed response.
-	// -32000 Error code will result in returning a 500 HTTP Status Code to the client.
-	errCodeUnmarshaling = -32000
+	// `jsonrpc.ResponseCodeBackendServerErr`, i.e. code -31002, will result in returning a 500 HTTP Status Code to the client.
+	errCodeUnmarshaling = jsonrpc.ResponseCodeBackendServerErr
 
 	// errMsgUnmarshaling is the generic message returned to the user if the endpoint returns a malformed response.
 	errMsgUnmarshaling = "the response returned by the endpoint is not a valid JSON-RPC response"