docs/test(binder): clarify BindingError JSON + cover empty-message fallback (#2771)

- Note on the struct that serialization goes through MarshalJSON (the json
  tags are documentation only now).
- Add a test for the empty-message -> status-text fallback branch.

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

Author: vishr

binder.go

@@ -66,6 +66,9 @@ import (
 */
 
 // BindingError represents an error that occurred while binding request data.
+//
+// Note: JSON serialization is handled by the MarshalJSON method below, not by the
+// struct tags (which are kept for documentation). MarshalJSON emits {"field","message"}.
 type BindingError struct {
 	// Field is the field name where value binding failed
 	Field string `json:"field"`

binder_error_response_test.go

@@ -33,3 +33,14 @@ func TestBindingError_serializesToStructuredJSON(t *testing.T) {
 	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")
 }
+
+// When the binding error carries no message, MarshalJSON falls back to the
+// status text (mirroring DefaultHTTPErrorHandler's *HTTPError branch).
+func TestBindingError_marshalJSON_emptyMessageFallsBackToStatusText(t *testing.T) {
+	be := &BindingError{Field: "name", HTTPError: &HTTPError{Code: http.StatusBadRequest}}
+
+	b, err := be.MarshalJSON()
+
+	assert.NoError(t, err)
+	assert.JSONEq(t, `{"field":"name","message":"Bad Request"}`, string(b))
+}