Refactor REST error handling based on PR comments

- Refactor mapping to use a namedtuple for RestErrorMap
- Extract _build_error_payload helper function for error responses
- Fix truthiness check for error data in logs

Author: knapg

src/a2a/utils/error_handlers.py

@@ -21,12 +21,38 @@
     A2A_REST_ERROR_MAPPING,
     A2AError,
     InternalError,
+    RestErrorMap,
 )
 
 
 logger = logging.getLogger(__name__)
 
 
+def _build_error_payload(
+    code: int,
+    status: str,
+    message: str,
+    reason: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Helper function to build the JSON error payload."""
+    payload: dict[str, Any] = {
+        'code': code,
+        'status': status,
+        'message': message,
+    }
+    if reason:
+        payload['details'] = [
+            {
+                '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+                'reason': reason,
+                'domain': 'a2a-protocol.org',
+                'metadata': metadata if metadata is not None else {},
+            }
+        ]
+    return {'error': payload}
+
+
 def rest_error_handler(
     func: Callable[..., Awaitable[Response]],
 ) -> Callable[..., Awaitable[Response]]:
@@ -37,9 +63,12 @@ async def wrapper(*args: Any, **kwargs: Any) -> Response:
         try:
             return await func(*args, **kwargs)
         except A2AError as error:
-            http_code, grpc_status, reason = A2A_REST_ERROR_MAPPING.get(
-                type(error), (500, 'INTERNAL', 'INTERNAL_ERROR')
+            mapping = A2A_REST_ERROR_MAPPING.get(
+                type(error), RestErrorMap(500, 'INTERNAL', 'INTERNAL_ERROR')
             )
+            http_code = mapping.http_code
+            grpc_status = mapping.grpc_status
+            reason = mapping.reason
 
             log_level = (
                 logging.ERROR
@@ -51,62 +80,44 @@ async def wrapper(*args: Any, **kwargs: Any) -> Response:
                 "Request error: Code=%s, Message='%s'%s",
                 getattr(error, 'code', 'N/A'),
                 getattr(error, 'message', str(error)),
-                f', Data={error.data}' if hasattr(error, 'data') else '',
+                f', Data={error.data}' if error.data else '',
             )
 
             # SECURITY WARNING: Data attached to A2AError.data is serialized unaltered and exposed publicly to the client in the REST API response.
             metadata = getattr(error, 'data', None) or {}
 
             return JSONResponse(
-                content={
-                    'error': {
-                        'code': http_code,
-                        'status': grpc_status,
-                        'message': getattr(error, 'message', str(error)),
-                        'details': [
-                            {
-                                '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
-                                'reason': reason,
-                                'domain': 'a2a-protocol.org',
-                                'metadata': metadata,
-                            }
-                        ],
-                    }
-                },
+                content=_build_error_payload(
+                    code=http_code,
+                    status=grpc_status,
+                    message=getattr(error, 'message', str(error)),
+                    reason=reason,
+                    metadata=metadata,
+                ),
                 status_code=http_code,
                 media_type='application/json',
             )
         except ParseError as error:
             logger.warning('Parse error: %s', str(error))
             return JSONResponse(
-                content={
-                    'error': {
-                        'code': 400,
-                        'status': 'INVALID_ARGUMENT',
-                        'message': str(error),
-                        'details': [
-                            {
-                                '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
-                                'reason': 'INVALID_REQUEST',
-                                'domain': 'a2a-protocol.org',
-                                'metadata': {},
-                            }
-                        ],
-                    }
-                },
+                content=_build_error_payload(
+                    code=400,
+                    status='INVALID_ARGUMENT',
+                    message=str(error),
+                    reason='INVALID_REQUEST',
+                    metadata={},
+                ),
                 status_code=400,
                 media_type='application/json',
             )
         except Exception:
             logger.exception('Unknown error occurred')
             return JSONResponse(
-                content={
-                    'error': {
-                        'code': 500,
-                        'status': 'INTERNAL',
-                        'message': 'unknown exception',
-                    }
-                },
+                content=_build_error_payload(
+                    code=500,
+                    status='INTERNAL',
+                    message='unknown exception',
+                ),
                 status_code=500,
                 media_type='application/json',
             )
@@ -134,9 +145,7 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
                 "Request error: Code=%s, Message='%s'%s",
                 getattr(error, 'code', 'N/A'),
                 getattr(error, 'message', str(error)),
-                ', Data=' + str(getattr(error, 'data', ''))
-                if getattr(error, 'data', None)
-                else '',
+                f', Data={error.data}' if error.data else '',
             )
             # Since the stream has started, we can't return a JSONResponse.
             # Instead, we run the error handling logic (provides logging)

src/a2a/utils/errors.py

@@ -4,6 +4,16 @@
 as well as server exception classes.
 """
 
+from typing import NamedTuple
+
+
+class RestErrorMap(NamedTuple):
+    """Named tuple mapping HTTP status, gRPC status, and reason strings."""
+
+    http_code: int
+    grpc_status: str
+    reason: str
+
 
 class A2AError(Exception):
     """Base exception for A2A errors."""
@@ -110,6 +120,7 @@ class VersionNotSupportedError(A2AError):
     'InvalidRequestError',
     'MethodNotFoundError',
     'PushNotificationNotSupportedError',
+    'RestErrorMap',
     'TaskNotCancelableError',
     'TaskNotFoundError',
     'UnsupportedOperationError',
@@ -134,43 +145,53 @@ class VersionNotSupportedError(A2AError):
 }
 
 
-A2A_REST_ERROR_MAPPING: dict[type[A2AError], tuple[int, str, str]] = {
-    TaskNotFoundError: (404, 'NOT_FOUND', 'TASK_NOT_FOUND'),
-    TaskNotCancelableError: (409, 'FAILED_PRECONDITION', 'TASK_NOT_CANCELABLE'),
-    PushNotificationNotSupportedError: (
+A2A_REST_ERROR_MAPPING: dict[type[A2AError], RestErrorMap] = {
+    TaskNotFoundError: RestErrorMap(404, 'NOT_FOUND', 'TASK_NOT_FOUND'),
+    TaskNotCancelableError: RestErrorMap(
+        409, 'FAILED_PRECONDITION', 'TASK_NOT_CANCELABLE'
+    ),
+    PushNotificationNotSupportedError: RestErrorMap(
         400,
         'UNIMPLEMENTED',
         'PUSH_NOTIFICATION_NOT_SUPPORTED',
     ),
-    UnsupportedOperationError: (400, 'UNIMPLEMENTED', 'UNSUPPORTED_OPERATION'),
-    ContentTypeNotSupportedError: (
+    UnsupportedOperationError: RestErrorMap(
+        400, 'UNIMPLEMENTED', 'UNSUPPORTED_OPERATION'
+    ),
+    ContentTypeNotSupportedError: RestErrorMap(
         415,
         'INVALID_ARGUMENT',
         'CONTENT_TYPE_NOT_SUPPORTED',
     ),
-    InvalidAgentResponseError: (502, 'INTERNAL', 'INVALID_AGENT_RESPONSE'),
-    ExtendedAgentCardNotConfiguredError: (
+    InvalidAgentResponseError: RestErrorMap(
+        502, 'INTERNAL', 'INVALID_AGENT_RESPONSE'
+    ),
+    ExtendedAgentCardNotConfiguredError: RestErrorMap(
         400,
         'FAILED_PRECONDITION',
         'EXTENDED_AGENT_CARD_NOT_CONFIGURED',
     ),
-    ExtensionSupportRequiredError: (
+    ExtensionSupportRequiredError: RestErrorMap(
         400,
         'FAILED_PRECONDITION',
         'EXTENSION_SUPPORT_REQUIRED',
     ),
-    VersionNotSupportedError: (400, 'UNIMPLEMENTED', 'VERSION_NOT_SUPPORTED'),
-    InvalidParamsError: (400, 'INVALID_ARGUMENT', 'INVALID_PARAMS'),
-    InvalidRequestError: (400, 'INVALID_ARGUMENT', 'INVALID_REQUEST'),
-    MethodNotFoundError: (404, 'NOT_FOUND', 'METHOD_NOT_FOUND'),
-    InternalError: (500, 'INTERNAL', 'INTERNAL_ERROR'),
+    VersionNotSupportedError: RestErrorMap(
+        400, 'UNIMPLEMENTED', 'VERSION_NOT_SUPPORTED'
+    ),
+    InvalidParamsError: RestErrorMap(400, 'INVALID_ARGUMENT', 'INVALID_PARAMS'),
+    InvalidRequestError: RestErrorMap(
+        400, 'INVALID_ARGUMENT', 'INVALID_REQUEST'
+    ),
+    MethodNotFoundError: RestErrorMap(404, 'NOT_FOUND', 'METHOD_NOT_FOUND'),
+    InternalError: RestErrorMap(500, 'INTERNAL', 'INTERNAL_ERROR'),
 }
 
 
 A2A_ERROR_REASONS = {
-    cls: reason for cls, (_, _, reason) in A2A_REST_ERROR_MAPPING.items()
+    cls: mapping.reason for cls, mapping in A2A_REST_ERROR_MAPPING.items()
 }
 
 A2A_REASON_TO_ERROR = {
-    reason: cls for cls, (_, _, reason) in A2A_REST_ERROR_MAPPING.items()
+    mapping.reason: cls for cls, mapping in A2A_REST_ERROR_MAPPING.items()
 }