[Feature Request] GRPC Status Codes and Error Handling

[karenyrx]

Is your feature request related to a problem? Please describe

Users of the transport-grpc plugin should receive appropriate gRPC status codes and consistent error messages regardless of whether they use the REST API or gRPC API. Some examples of inapprorpiate or unidiomatic error handling shown below

Issue 1: GRPC Status Codes

• Current: gRPC errors all get mapped to INTERNAL, making it impossible to distinguish between what should / should not be retried.
• Proposed fix: Errors should be mapped appropriately to fine-grained GRPC status codes

Issue 2: HTTP Status Codes in GRPC Responses

• Current: In the GRPC responses, it is still returning HTTP status codes instead of GRPC status codes (e.g. Bulk Response)

ResponseItem {
  status: 201  // HTTP Created status code
}

• Proposed fix: Should return gRPC status codes in protobuf responses

ResponseItem {
  status: 0    // gRPC OK status code
}

Issue 3: Error message inconsistency

• Current: Different error formats

// HTTP API: "OpenSearchException[Index not found]"
// gRPC API: "Index not found" (lost exception type context)

• Proposed Fix: Should have identical error format

// Both APIs: "OpenSearchException[Index not found]"
// Preserves exception type and unwrapping logic

Describe the solution you'd like

Preliminary ideas on how to fix the issues above.

1: Exception-to-Status Code Mapping

We propose to establish a definitive mapping for all HTTP status codes to GRPC status codes, as fololws:

1xx Informational

HTTP Status	HTTP Code	gRPC Status	gRPC Code
CONTINUE	100	OK	0
SWITCHING_PROTOCOLS	101	OK	0

2xx Success

HTTP Status	HTTP Code	gRPC Status	gRPC Code
OK	200	OK	0
CREATED	201	OK	0
ACCEPTED	202	OK	0
NON_AUTHORITATIVE_INFORMATION	203	OK	0
NO_CONTENT	204	OK	0
RESET_CONTENT	205	OK	0
PARTIAL_CONTENT	206	OK	0
MULTI_STATUS	207	OK	0

3xx Redirection

HTTP Status	HTTP Code	gRPC Status	gRPC Code
MULTIPLE_CHOICES	300	FAILED_PRECONDITION	9
MOVED_PERMANENTLY	301	FAILED_PRECONDITION	9
FOUND	302	FAILED_PRECONDITION	9
SEE_OTHER	303	FAILED_PRECONDITION	9
NOT_MODIFIED	304	FAILED_PRECONDITION	9
USE_PROXY	305	FAILED_PRECONDITION	9
TEMPORARY_REDIRECT	307	FAILED_PRECONDITION	9

4xx Client Errors

HTTP Status	HTTP Code	gRPC Status	gRPC Code
BAD_REQUEST	400	INVALID_ARGUMENT	3
UNAUTHORIZED	401	UNAUTHENTICATED	16
PAYMENT_REQUIRED	402	PERMISSION_DENIED	7
FORBIDDEN	403	PERMISSION_DENIED	7
NOT_FOUND	404	NOT_FOUND	5
METHOD_NOT_ALLOWED	405	UNIMPLEMENTED	12
NOT_ACCEPTABLE	406	INVALID_ARGUMENT	3
PROXY_AUTHENTICATION	407	UNAUTHENTICATED	16
REQUEST_TIMEOUT	408	DEADLINE_EXCEEDED	4
CONFLICT	409	ABORTED	10
GONE	410	NOT_FOUND	5
LENGTH_REQUIRED	411	FAILED_PRECONDITION	9
PRECONDITION_FAILED	412	FAILED_PRECONDITION	9
REQUEST_ENTITY_TOO_LARGE	413	OUT_OF_RANGE	11
REQUEST_URI_TOO_LONG	414	INVALID_ARGUMENT	3
UNSUPPORTED_MEDIA_TYPE	415	INVALID_ARGUMENT	3
REQUESTED_RANGE_NOT_SATISFIED	416	OUT_OF_RANGE	11
EXPECTATION_FAILED	417	FAILED_PRECONDITION	9
MISDIRECTED_REQUEST	421	INVALID_ARGUMENT	3
UNPROCESSABLE_ENTITY	422	INVALID_ARGUMENT	3
LOCKED	423	FAILED_PRECONDITION	9
FAILED_DEPENDENCY	424	FAILED_PRECONDITION	9
TOO_MANY_REQUESTS	429	RESOURCE_EXHAUSTED	8

5xx Server Errors

HTTP Status	HTTP Code	gRPC Status	gRPC Code
INTERNAL_SERVER_ERROR	500	INTERNAL	13
NOT_IMPLEMENTED	501	UNIMPLEMENTED	12
BAD_GATEWAY	502	UNAVAILABLE	14
SERVICE_UNAVAILABLE	503	UNAVAILABLE	14
GATEWAY_TIMEOUT	504	DEADLINE_EXCEEDED	4
HTTP_VERSION_NOT_SUPPORTED	505	UNIMPLEMENTED	12
INSUFFICIENT_STORAGE	507	RESOURCE_EXHAUSTED	8

Unknown Status Codes

HTTP Status	HTTP Code	gRPC Status	gRPC Code
Any unmapped status	N/A	UNKNOWN	2

2: Refactor/reused HTTP Exception handling code path to be reusable by GRPC

We propose to refactor ExceptionHandler.java into common utiities methods that can be reused for both HTTP and GRPC. Notably, the summaryMessage, unwrapCause, and stackTrace() methods can be reused, and some error message strings can be extracted into constants.

3. Follow the logic laid in in HTTP side for wrapping errors, as in GRPC

E.g. ExceptionsHandler#status is used to map Exceptions to REST statuses. We should follow a similar Exception to GRPC Status code mapping as well.

Related component

Libraries

Describe alternatives you've considered

No response

Additional context

No response