fix(binder): serialize BindingError to structured JSON (#2771)

BindingError embeds *HTTPError but did not implement json.Marshaler, so
DefaultHTTPErrorHandler's type switch fell through to its default branch
(the value is a *BindingError, not a *HTTPError), flattening responses to
{"message":"Bad Request"} and dropping both the field name and the binder
message — a regression from fbfe216.

Implement MarshalJSON on *BindingError so it takes the handler's
json.Marshaler branch, restoring the structured {"field":...,"message":...}
response (the v4.10.2 behavior).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vishr

binder.go

@@ -88,6 +88,24 @@ func (be *BindingError) Error() string {
 	return fmt.Sprintf("%s, field=%s", be.HTTPError.Error(), be.Field)
 }
 
+// MarshalJSON implements json.Marshaler so that binding errors are serialized into
+// a structured response (e.g. {"field":"id","message":"..."}) rather than being
+// flattened to a generic message. DefaultHTTPErrorHandler routes errors that
+// implement json.Marshaler through their own encoding.
+func (be *BindingError) MarshalJSON() ([]byte, error) {
+	message := be.Message
+	if message == "" {
+		message = http.StatusText(be.Code)
+	}
+	return json.Marshal(struct {
+		Field   string `json:"field"`
+		Message string `json:"message"`
+	}{
+		Field:   be.Field,
+		Message: message,
+	})
+}
+
 // ValueBinder provides utility methods for binding query or path parameter to various Go built-in types
 type ValueBinder struct {
 	// ValueFunc is used to get single parameter (first) value from request

binder_error_response_test.go

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: © 2015 LabStack LLC and Echo contributors
+
+package echo
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// Regression test for #2771: a BindingError returned from a handler must be
+// serialized by DefaultHTTPErrorHandler into a structured response that retains
+// the field name (and the binder message), not flattened to {"message":"Bad Request"}.
+func TestBindingError_serializesToStructuredJSON(t *testing.T) {
+	e := New()
+	e.GET("/doc", func(c *Context) error {
+		var docNum int
+		return QueryParamsBinder(c).MustInt("docNum", &docNum).BindError()
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/doc?docNum=abc", nil)
+	rec := httptest.NewRecorder()
+	e.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+
+	var body map[string]any
+	assert.NoError(t, json.Unmarshal(rec.Body.Bytes(), &body))
+	assert.Equal(t, "docNum", body["field"], "binding error response must retain the field name")
+	assert.Equal(t, "failed to bind field value to int", body["message"], "binding error response must retain the binder message")
+}