[TT-16767][Global] [Implementation] Centralised Error Overrides Infrastructure

config/config.go

@@ -13,6 +13,7 @@
 	"github.com/kelseyhightower/envconfig"
 
 	"github.com/TykTechnologies/tyk/apidef"
+	"github.com/TykTechnologies/tyk/internal/errors"
 	"github.com/TykTechnologies/tyk/internal/otel"
 	logger "github.com/TykTechnologies/tyk/log"
 	"github.com/TykTechnologies/tyk/regexp"
@@ -1339,6 +1340,25 @@
 	// ```
 	OverrideMessages map[string]TykError `bson:"override_messages" json:"override_messages"`
 
+	// ErrorOverrides allows you to customize the error responses that the Gateway will return to API clients.
+	// This configuration will be used to override both Gateway-generated errors (e.g. authentication failures, rate limits, validation errors)
+	// and errors returned by the upstream service (4xx/5xx responses from backend APIs).
+	// Rules are organized by HTTP status code and can include additional matching criteria.
+	// These rules will be superseded by any overrides configured in the API definition
+	//
+	// Sample Override Setting
+	// ```
+	// "error_overrides": {
+	//   "500": [{
+	//     "response": {
+	//       "code": 503,
+	//       "body": "{\"error\": \"Service temporarily unavailable\"}"
+	//     }
+	//   }]
+	// }
+	// ```
+	ErrorOverrides ErrorOverridesMap `json:"error_overrides,omitempty"`
+
 	// Cloud flag shows the Gateway runs in Tyk Cloud.
 	Cloud bool `json:"cloud"`
 
@@ -1407,6 +1427,105 @@
 	Code    int    `json:"code"`
 }
 
+// ErrorMatcher defines additional matching criteria for error overrides.
+type ErrorMatcher struct {
+	// Flag matches against the error classification flag from the request context.
+	Flag errors.ResponseFlag `json:"flag,omitempty"`
+
+	// MessagePattern is a regex pattern to match against the response body.
+	MessagePattern string `json:"message_pattern,omitempty"`
+
+	// BodyField is a JSON path (gjson syntax) to extract a value from the response body.
+	BodyField string `json:"body_field,omitempty"`
+
+	// BodyValue is the expected value at BodyField for the match to succeed.
+	BodyValue string `json:"body_value,omitempty"`
+
+	// CompiledPattern is the pre-compiled regex for MessagePattern.
+	CompiledPattern *regexp.Regexp `json:"-" ignored:"true"`
+}
+
+// Compile compiles the MessagePattern regex if present.
+// Should be called after unmarshaling from JSON or YAML.
+func (m *ErrorMatcher) Compile() error {
+	if m.MessagePattern != "" && m.CompiledPattern == nil {
+		re, err := regexp.Compile(m.MessagePattern)
+		if err != nil {
+			return fmt.Errorf("invalid regex pattern %q: %w", m.MessagePattern, err)
+		}
+
+		m.CompiledPattern = re
+	}
+
+	return nil
+}
+
+// ErrorResponse defines the override response for error overrides.
+type ErrorResponse struct {
+	// Code is the HTTP status code to return.
+	Code int `json:"code"`
+
+	// Body is the HTTP response body (literal or inline template).
+	Body string `json:"body,omitempty"`
+
+	// Message is the semantic error message passed to templates as {{.Message}}.
+	Message string `json:"message,omitempty"`
+
+	// Template references an error template file in the templates/ directory.
+	Template string `json:"template,omitempty"`
+
+	// Headers are HTTP headers to include in the response.
+	Headers map[string]string `json:"headers,omitempty"`
+}
+
+// ErrorOverride combines an optional matcher with its response.
+type ErrorOverride struct {
+	// Match contains optional additional matching criteria.
+	Match *ErrorMatcher `json:"match,omitempty"`
+
+	// Response defines the response to return when matched.
+	Response ErrorResponse `json:"response"`
+
+	// compiledBodyTmpl is the pre-compiled text/template for inline Body.
+	compiledBodyTmpl any `json:"-" ignored:"true"`
+
+	// compiledBodyTmplHTML is the pre-compiled html/template for inline Body.
+	compiledBodyTmplHTML any `json:"-" ignored:"true"`
+}
+
+// SetCompiledTemplates stores the pre-compiled templates for inline Body.
+func (e *ErrorOverride) SetCompiledTemplates(textTmpl, htmlTmpl any) {
+	e.compiledBodyTmpl = textTmpl
+	e.compiledBodyTmplHTML = htmlTmpl
+}
+
+// GetCompiledTemplate returns the pre-compiled template for the given content type.
+// Returns nil if no inline Body template was compiled (e.g., using file template).
+func (e *ErrorOverride) GetCompiledTemplate(isXML bool) interface{} {
+	if isXML {
+		return e.compiledBodyTmpl
+	}
+
+	return e.compiledBodyTmplHTML
+}
+
+// HasCompiledTemplate returns true if this override has a pre-compiled inline Body template.
+func (e *ErrorOverride) HasCompiledTemplate() bool {
+	return e.compiledBodyTmpl != nil
+}
+
+// ErrorOverridesMap maps status codes to their override rules.
+type ErrorOverridesMap map[string][]ErrorOverride
+
+// CompiledErrorOverrides provides lookup for error overrides by status code.
+type CompiledErrorOverrides struct {
+	// ByExactCode maps exact status codes to their override rules.
+	ByExactCode map[int][]*ErrorOverride
+
+	// ByPrefix maps status code prefixes to pattern rules.
+	ByPrefix map[int][]*ErrorOverride
+}
+
 // VaultConfig is used to configure the creation of a client
 // This is a stripped down version of the config structure in vault's API client
 type VaultConfig struct {