Enforce the Content-Type Header in a Spring Boot REST API

When developing RESTful APIs with Spring Boot, ensuring that clients send well-formed and properly annotated requests is essential. One of the most common issues arises when a request is missing critical headers — such as the Content-Type header, which tells the server how to interpret the body of the request.

In this article, we’ll explore how to make the Content-Type header mandatory in a Spring Boot controller method and how to return a 400 Bad Request response when it’s not provided.

🧩 Why the Content-Type Header Matters

The Content-Type header tells the server how to parse the request body. For example:

• application/json — the request body contains JSON data
• application/xml — the request body contains XML data
• application/x-www-form-urlencoded — the request body contains form data

Without this header, the server may misinterpret the payload or even fail to process the request altogether.

In security-sensitive or payment-related APIs, missing headers should never be ignored. Instead, the API should respond with a 400 Bad Request error, informing the client that the request was malformed.

⚙️ Controller Example

Here’s how you can enforce the Content-Type header requirement in a Spring Boot REST endpoint:

@PostMapping("/payments/{payment-product}")
public ResponseEntity<GenericResponse<Object>> createPayment(
        @RequestHeader Map<String, String> headers,
        @RequestBody PaymentBodyConfiguration paymentBodyConfiguration,
        @PathVariable(name = "payment-product") String paymentProduct,
        @RequestHeader("authToken") String authToken,
        @RequestHeader("X-Request-ID") String xRequestId,
        @RequestHeader("Protocol-Version") String protocolVersion,
        @RequestHeader(value = "Content-Type", required = false) String contentType,
        @RequestHeader("institutionName") String bankId,
        @RequestHeader(value = "PSU-IP-Address", required = false) String psuIpAddress,
        @RequestHeader(value = "PSU-ID-Type", required = false) String psuIdType,
        @RequestHeader(value = "PSU-Corporate-ID", required = false) String psuCorporateId,
        @RequestHeader(value = "PSU-Corporate-ID-Type", required = false) String psuCorporateIdType,
        @RequestHeader(value = "TPP-Redirect-Preferred", required = false) boolean tppRedirectPreferred,
        @RequestHeader(value = "TPP-Redirect-URI", required = false) String tppRedirectUri,
        @RequestHeader(value = "TPP-Nok-Redirect-URI", required = false) String tppNokRedirectUri) {

    // Validate the presence of Content-Type
    if (contentType == null || contentType.isEmpty()) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(new GenericResponse<>()
                .withStatus(HttpStatus.BAD_REQUEST)
                .withMessage("Missing or invalid 'Content-Type' header"));
    }

    // Proceed with payment creation logic
    return ResponseEntity.ok(new GenericResponse<>()
            .withStatus(HttpStatus.OK)
            .withMessage("Payment created successfully"));
}

🧱 Handling Missing Headers Globally

Spring Boot allows you to handle exceptions such as missing headers using an @ExceptionHandler.
This helps standardize your error responses across all controllers.

@ExceptionHandler(value = {MissingRequestHeaderException.class, MissingPathVariableException.class})
public ResponseEntity<Object> handleBadFormatRequestException(Exception exception) {
    log.error("HandleBadFormatRequestException: BAD_REQUEST: {}", exception.getMessage());

    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(new GenericResponse<>()
            .withStatus(HttpStatus.BAD_REQUEST)
            .withMessage("Missing parameters in the header or path"));
}

With this approach, even if a required header is missing elsewhere in your API, your application will respond consistently with a clear message.

🧠 Best Practices

1. Validate early: Check required headers as soon as the request reaches your controller.
2. Use consistent responses: Return structured JSON responses, ideally using a standardized response wrapper.
3. Avoid “silent failures”: Never proceed with business logic if critical headers are missing.
4. Document your API: Use OpenAPI/Swagger annotations to clearly state which headers are mandatory.
5. Add integration tests: Ensure automated tests verify behavior when headers are missing or invalid.

✅ Example of a 400 Bad Request Response

If the Content-Type header is missing, the server should return a response like this:

{
  "status": 400,
  "message": "Missing or invalid 'Content-Type' header"
}

This makes it easy for API clients to understand what went wrong and how to fix it.

🚀 Conclusion

Enforcing the Content-Type header in Spring Boot is a small but crucial step in building robust and secure APIs. By validating headers before processing requests and returning consistent error messages, you help clients send valid data and protect your backend from unexpected input.

Implementing simple validation checks like this improves reliability, enhances security, and simplifies debugging — ensuring your API behaves predictably under all conditions.