Global Runtime Exception Handler

Overview

The GlobalRuntimeExceptionHandler is a system component that acts as a centralized, catch-all error handler for the API runtime service. Its primary purpose is to intercept any unexpected exceptions that are not handled by specific API endpoint logic.

This handler solves a critical problem: preventing unhandled exceptions from propagating to the underlying web framework, which would otherwise result in a generic, uninformative HTTP 500 error with an empty body. Instead, the GlobalRuntimeExceptionHandler ensures that every unexpected failure produces a standardized, structured JSON error response.

This component guarantees:

• Consistent Error Shape: All unhandled errors are returned in a predictable JSON format containing an error code, a message, and a correlation ID.
• Improved Diagnosability: A unique correlation ID is included in every error response and the corresponding server log, enabling faster troubleshooting by linking a specific client error to detailed internal logs.
• Enhanced Security: Sensitive internal details, such as exception types and stack traces, are never exposed in the API response. They are written exclusively to server-side logs.

The handler operates on exceptions that escape from controller methods. It does not intercept successfully returned responses, including structured error responses that are intentionally returned by API logic (e.g., validation failures from the RuntimeController).

How It Works

The GlobalRuntimeExceptionHandler is implemented as a RestControllerAdvice, allowing it to intercept exceptions from any controller within the runtime service. It contains logic to differentiate between various types of exceptions and respond accordingly.

flowchart TD
    A[Exception escapes controller] --> B{Global Handler intercepts};
    B --> C{Is it `UnboundTenantException`?};
    C -- Yes --> D[Return HTTP 401 / S2R-RUN-0401];
    C -- No --> E{Is it a Spring `ErrorResponse`?};
    E -- Yes --> F[Rethrow to Spring default handler<br>(preserves 4xx status)];
    E -- No --> G[Treat as unhandled internal error];
    G --> H[Log full exception details internally];
    H --> I[Return HTTP 500 / S2R-RUN-0500];

The processing flow is as follows:

1. An exception is thrown from a controller and is not caught by any more specific handler.
2. The GlobalRuntimeExceptionHandler intercepts the exception.
3. Tenant Authentication Check: It first checks if the exception is an UnboundTenantException. If so, it signifies a request that requires tenant context was processed without one. The handler logs a warning and returns a specific HTTP 401 error.
4. Framework Error Check: If not a tenant exception, it checks if the exception is an instance of Spring's ErrorResponse. These exceptions are typically generated by the framework itself for issues like a non-existent route (404 Not Found) or an unsupported HTTP method (405 Method Not Allowed). The handler re-throws these exceptions, allowing Spring's default mechanism to handle them and preserve their original, correct HTTP 4xx status code.
5. Unhandled Internal Error: Any other exception is treated as a true, unhandled internal server error.
   • A correlation ID is resolved or generated.
   • The full exception, including its stack trace, is logged internally at the ERROR level along with the correlation ID.
   • A generic HTTP 500 error response is constructed and returned to the API consumer.

Correlation ID Handling

A correlation ID is used to link an error response received by an API consumer to the detailed diagnostic logs on the server. The ID is resolved as follows:

1. The handler inspects the incoming request for an X-Correlation-Id header.
2. If the header is present and contains a valid UUID, that value is used.
3. If the header is missing, empty, or contains a value that is not a valid UUID, a new, random UUID is generated.

The resulting correlation ID is included in both the X-Correlation-Id response header and the JSON error body.

Error Response Format

When the handler generates an error, it returns a standard HTTP response with a specific body structure.

• Status Codes:
  • 500 Internal Server Error: For generic, unhandled exceptions.
  • 401 Unauthorized: For UnboundTenantException.
• Headers:
  • X-Correlation-Id: Contains the correlation ID for the request.
• Body: A JSON object with the following structure.

Example Error Response

This example shows the response for a generic unhandled exception.

{
  "error": {
    "code": "S2R-RUN-0500",
    "message": "An unexpected internal error occurred",
    "details": {
      "path": "/some/api/endpoint"
    },
    "correlationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response Body Fields

The response body is a JSON object containing a single top-level error key.

Configuration

The GlobalRuntimeExceptionHandler is not externally configurable. Its behavior, including error codes and messages, is defined by static constants within the service and cannot be modified via application properties or environment variables.

Troubleshooting

The handler produces the following distinct error codes.

See Also

• Runtime Controller: The primary controller for API execution, which may return its own set of structured error responses for handled conditions like input validation failures. These are not processed by the global handler.
• Tenant Authentication: The mechanism responsible for authenticating and establishing tenant context for incoming requests. Failures in this process can lead to the S2R-RUN-0401 error.

All SOAP-to-REST docs