pandaproxy: fix unmatched-route 404 body shape

src/v/pandaproxy/BUILD

@@ -113,6 +113,24 @@ redpanda_cc_library(
     ],
 )
 
+redpanda_cc_library(
+    name = "default_404_handler",
+    srcs = [
+        "default_404_handler.cc",
+    ],
+    hdrs = [
+        "default_404_handler.h",
+    ],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":error",
+        ":error_reply",
+        ":json",
+        "//src/v/base",
+        "@seastar",
+    ],
+)
+
 redpanda_cc_library(
     name = "core",
     srcs = [
@@ -131,6 +149,7 @@ redpanda_cc_library(
     ],
     visibility = ["//visibility:public"],
     deps = [
+        ":default_404_handler",
         ":error",
         ":error_reply",
         ":json",

src/v/pandaproxy/default_404_handler.cc

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2026 Redpanda Data, Inc.
+ *
+ * Use of this software is governed by the Business Source License
+ * included in the file licenses/BSL.md
+ *
+ * As of the Change Date specified in that file, in accordance with
+ * the Business Source License, use of this software will be governed
+ * by the Apache License, Version 2.0
+ */
+
+#include "pandaproxy/default_404_handler.h"
+
+#include "pandaproxy/error.h"
+#include "pandaproxy/json/requests/error_reply.h"
+#include "pandaproxy/json/rjson_util.h"
+
+#include <seastar/core/future.hh>
+#include <seastar/http/reply.hh>
+#include <seastar/http/request.hh>
+
+#include <memory>
+#include <utility>
+
+namespace pandaproxy {
+
+ss::future<std::unique_ptr<ss::http::reply>> default_404_handler::handle(
+  const ss::sstring&,
+  std::unique_ptr<ss::http::request>,
+  std::unique_ptr<ss::http::reply> rep) {
+    auto ec = make_error_condition(reply_error_code::not_found);
+    json::error_body body{.ec = ec, .message = ss::sstring{ec.message()}};
+    rep->set_status(ss::http::reply::status_type::not_found);
+    rep->write_body(
+      _mime_type, pandaproxy::json::rjson_serialize_str(std::move(body)));
+    return ss::make_ready_future<std::unique_ptr<ss::http::reply>>(
+      std::move(rep));
+}
+
+} // namespace pandaproxy

src/v/pandaproxy/default_404_handler.h

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026 Redpanda Data, Inc.
+ *
+ * Use of this software is governed by the Business Source License
+ * included in the file licenses/BSL.md
+ *
+ * As of the Change Date specified in that file, in accordance with
+ * the Business Source License, use of this software will be governed
+ * by the Apache License, Version 2.0
+ */
+
+#pragma once
+
+#include "base/seastarx.h"
+
+#include <seastar/core/future.hh>
+#include <seastar/core/sstring.hh>
+#include <seastar/http/handlers.hh>
+#include <seastar/http/reply.hh>
+#include <seastar/http/request.hh>
+
+#include <memory>
+#include <utility>
+
+namespace pandaproxy {
+
+/// \brief Default handler for unmatched (method, path) combinations on a
+/// pandaproxy::server. Emits the schema-registry/REST-proxy error body
+/// {"error_code": 404, "message": "HTTP 404 Not Found"} (with error_code
+/// instead of Seastar's fallback code field) so clients parsing this
+/// envelope get the shape they expect.
+class default_404_handler : public ss::httpd::handler_base {
+public:
+    explicit default_404_handler(ss::sstring mime_type)
+      : _mime_type(std::move(mime_type)) {}
+
+    ss::future<std::unique_ptr<ss::http::reply>> handle(
+      const ss::sstring&,
+      std::unique_ptr<ss::http::request>,
+      std::unique_ptr<ss::http::reply> rep) final;
+
+private:
+    ss::sstring _mime_type;
+};
+
+} // namespace pandaproxy

src/v/pandaproxy/server.cc

@@ -12,6 +12,7 @@
 #include "model/metadata.h"
 #include "net/dns.h"
 #include "net/tls_certificate_probe.h"
+#include "pandaproxy/default_404_handler.h"
 #include "pandaproxy/json/types.h"
 #include "pandaproxy/logger.h"
 #include "pandaproxy/probe.h"
@@ -258,6 +259,10 @@ ss::future<> server::start(
     _server._routes.register_exeption_handler(
       exception_replier{ss::sstring{name(_exceptional_mime_type)}, _log});
 
+    _default_handler = std::make_unique<default_404_handler>(
+      ss::sstring{name(_exceptional_mime_type)});
+    _server._routes.add_default_handler(_default_handler.get());
+
     _probe = std::make_unique<server_probe>(_ctx, _public_metrics_group_name);
 
     _ctx.advertised_listeners.reserve(endpoints.size());
@@ -307,7 +312,7 @@ ss::future<> server::stop() {
     return _pending_reqs.close().finally([this]() {
         _ctx.as.request_abort();
         _probe.reset(nullptr);
-        return _server.stop();
+        return _server.stop().finally([this]() { _default_handler.reset(); });
     });
 }
 

src/v/pandaproxy/server.h

@@ -136,6 +136,7 @@ class server {
     ss::future<> stop();
 
 private:
+    std::unique_ptr<ss::httpd::handler_base> _default_handler;
     ss::httpd::http_server _server;
     ss::sstring _public_metrics_group_name;
     ss::gate _pending_reqs;

src/v/pandaproxy/test/BUILD

@@ -79,3 +79,19 @@ redpanda_cc_btest(
         "@seastar//:testing",
     ],
 )
+
+redpanda_cc_btest(
+    name = "default_404_handler_test",
+    timeout = "short",
+    srcs = [
+        "default_404_handler.cc",
+    ],
+    deps = [
+        "//src/v/json",
+        "//src/v/pandaproxy:default_404_handler",
+        "//src/v/test_utils:seastar_boost",
+        "@boost//:test",
+        "@seastar",
+        "@seastar//:testing",
+    ],
+)

src/v/pandaproxy/test/default_404_handler.cc

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2026 Redpanda Data, Inc.
+ *
+ * Use of this software is governed by the Business Source License
+ * included in the file licenses/BSL.md
+ *
+ * As of the Change Date specified in that file, in accordance with
+ * the Business Source License, use of this software will be governed
+ * by the Apache License, Version 2.0
+ */
+
+#include "pandaproxy/default_404_handler.h"
+
+#include "json/document.h"
+
+#include <seastar/http/reply.hh>
+#include <seastar/http/request.hh>
+#include <seastar/testing/thread_test_case.hh>
+
+#include <boost/test/tools/old/interface.hpp>
+#include <boost/test/unit_test.hpp>
+
+#include <memory>
+#include <string>
+
+namespace pp = pandaproxy;
+
+SEASTAR_THREAD_TEST_CASE(default_404_handler_emits_error_code_envelope) {
+    pp::default_404_handler handler{
+      ss::sstring{"application/vnd.schemaregistry.v1+json"}};
+
+    auto rep = handler
+                 .handle(
+                   ss::sstring{},
+                   std::make_unique<ss::http::request>(),
+                   std::make_unique<ss::http::reply>())
+                 .get();
+
+    BOOST_REQUIRE(rep != nullptr);
+    BOOST_REQUIRE_EQUAL(
+      static_cast<int>(rep->_status),
+      static_cast<int>(ss::http::reply::status_type::not_found));
+
+    json::Document doc;
+    doc.Parse(rep->_content.c_str(), rep->_content.size());
+    BOOST_REQUIRE(!doc.HasParseError());
+    BOOST_REQUIRE(doc.IsObject());
+
+    BOOST_REQUIRE(doc.HasMember("error_code"));
+    BOOST_REQUIRE(doc["error_code"].IsInt());
+    BOOST_REQUIRE_EQUAL(doc["error_code"].GetInt(), 404);
+
+    BOOST_REQUIRE(doc.HasMember("message"));
+    BOOST_REQUIRE(doc["message"].IsString());
+    BOOST_REQUIRE_EQUAL(
+      std::string(doc["message"].GetString()),
+      std::string("HTTP 404 Not Found"));
+
+    auto content_type_it = rep->_headers.find("Content-Type");
+    BOOST_REQUIRE(content_type_it != rep->_headers.end());
+    BOOST_REQUIRE_EQUAL(
+      content_type_it->second,
+      ss::sstring("application/vnd.schemaregistry.v1+json"));
+}

tests/rptest/tests/pandaproxy_test.py

@@ -502,6 +502,25 @@ def test_get_brokers(self):
 
         assert sorted(brokers) == sorted(node_idxs)
 
+    @cluster(num_nodes=3)
+    def test_unmatched_route_404_shape(self):
+        """
+        Unmatched routes on REST proxy must return the standard
+        {"error_code": <int>, "message": "..."} JSON envelope, not Seastar's
+        fallback {"message": "Not found", "code": 404}. The fix lives in
+        pandaproxy::server, which both REST proxy and schema registry share,
+        so this assertion mirrors the schema-registry-side test.
+        """
+        result_raw = requests.get(f"{self._base_uri()}/_no_such_path")
+        assert result_raw.status_code == requests.codes.not_found, (
+            f"expected 404, got {result_raw.status_code}: {result_raw.text}"
+        )
+
+        body = result_raw.json()
+        assert "error_code" in body, f"expected error_code field, got body={body}"
+        assert body["error_code"] == 404, f"expected error_code=404, got body={body}"
+        assert "message" in body, f"expected message field, got body={body}"
+
     @cluster(num_nodes=3)
     def test_list_topics_validation(self):
         """

tests/rptest/tests/schema_registry_test.py

@@ -1563,6 +1563,25 @@ def test_schemas_types(self):
         result = result_raw.json()
         assert set(result) == {"JSON", "PROTOBUF", "AVRO"}
 
+    @cluster(num_nodes=3)
+    def test_unmatched_route_404_shape(self):
+        """
+        Unmatched routes on schema registry must return the standard
+        {"error_code": <int>, "message": "..."} JSON envelope, not Seastar's
+        fallback {"message": "Not found", "code": 404}. SR clients parse
+        `error_code`; without this shape, fallback paths that inspect 404
+        bodies produce a 0-coded error.
+        """
+        result_raw = self.sr_client.request("GET", "_no_such_path")
+        assert result_raw.status_code == requests.codes.not_found, (
+            f"expected 404, got {result_raw.status_code}: {result_raw.text}"
+        )
+
+        body = result_raw.json()
+        assert "error_code" in body, f"expected error_code field, got body={body}"
+        assert body["error_code"] == 404, f"expected error_code=404, got body={body}"
+        assert "message" in body, f"expected message field, got body={body}"
+
     @cluster(num_nodes=3)
     def test_get_schema_id_versions(self):
         """