Implementing json Rest API as a Servlet Status Code eg 404 json Response overwritten by Default Error Page

[vhochsteinTef]

Hi,

I am using AEM as a Cloud Service and my Portal relies heavily on dynamic data, which I am offering by json Rest Services developed in AEM as well.
Best Practice is for REST to use HTTP Statuscodes, such as 404 for not found, or 400 for validation errors.

If I develop locally in my author instance everything is working fine. I get my defined json responses for eg 404.

However in the Cloud I am receiving the standard AEM 404 Error Page instead.

Any idea how I may convince Dispatcher ?? to just pass through my 404 json response returned by Servlet ?

thanks a for your support in advance

--

Volker

[ShivamKumar]

Hi @vhochsteinTef ,
I think this is behavior in AEM as a Cloud Service with Dispatcher: it intercepts 404 status codes and redirects to the AEM error handler (like /content/404.html), instead of returning your custom JSON response.

You can try to follow these steps - 

1. Update Dispatcher Config to Allow Error Passthrough 

# Allow all responses from your servlet, including 4xx and 5xx
/0200 { 
  /type "allow" 
  /method "GET"
  /url "/bin/myapi/.*"
  /status "400-599"
}

• /status "400-599" → Allows Dispatcher to pass through error status codes
• /url → Should match your servlet path (e.g. /bin/myapi/something)

2. Ensure servlet sets status & content-type correctly

response.setStatus(HttpServletResponse.SC_NOT_FOUND); // 404
response.setContentType("application/json");
response.getWriter().write("{\"error\": \"Item not found\"}");

3. Optionally Bypass AEM Global Error Handling - AEM’s default Sling error handler may still override responses. If needed:

• Overlay /apps/sling/servlet/errorhandler/404.jsp
• Detect JSON path or content-type and exit early, not rendering HTML.

Let me know if this process works.

[vhochsteinTef]

Hi,

thanks for the hint. Looks like that status key is unknown to dispatcher:

2025/07/09 10:44:42 /tmp/dispatcher/unzippedConfiguration/conf.dispatcher.d/filters/filters.any:37: entry not recognized: 'status'
  /tmp/dispatcher/unzippedConfiguration/conf.dispatcher.d/filters/filters.any:129: entry not recognized: 'status'
  /tmp/dispatcher/unzippedConfiguration/conf.dispatcher.d/filters/filters.any:37: entry not recognized: 'status'
  /tmp/dispatcher/unzippedConfiguration/conf.dispatcher.d/filters/filters.any:129: entry not recognized: 'status'