Spring Middleware defines a unified error handling model for Spring Boot microservices. It provides structured error responses, domain-specific error codes, and consistent propagation across service boundaries for both REST and GraphQL APIs.
Errors are not treated as raw HTTP responses or framework exceptions. The platform defines a consistent structure that allows clients and services to understand failures in a predictable and machine-readable way.
The same error model is used across the platform, regardless of the entry point or communication style.
All REST endpoints return errors using the same JSON structure, making error handling predictable for clients and consistent across services.
{
"statusCode": 404,
"statusMessage": "Not Found",
"code": "PRODUCT:NOT_FOUND",
"message": "Product not found",
"extensions": {}
}Errors produced by one service are propagated through the communication layer without losing structure or metadata.
Remote failures are wrapped into structured exceptions that expose remote service metadata and allow applications to inspect or translate errors.
GraphQL uses the same domain error codes, exposed through the extensions field.
{
"message": "Product not found",
"path": ["product"],
"extensions": {
"code": "PRODUCT:NOT_FOUND"
}
}Services should align with the error model to ensure consistency across the platform.
Use DOMAIN:KEY patterns like PRODUCT:NOT_FOUND or ORDER:INVALID_STATE.
Throw structured exceptions instead of raw runtime errors.
Translate low-level failures into domain-level errors.