Customizing Error Responses

Documentation Index

Fetch the complete documentation index at: https://tyk.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Availability

​

Tyk Gateway Error Handling

• the HTTP status code defined by the triggering middleware
• a Content-Type: application/json header
• an X-Generator: tyk.io header
• a JSON response body

HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Generator: tyk.io

{"error": "Access to this API has been disallowed"}

• the response is provided in JSON format regardless of the Content-Type of the request.
• the X-Generator header can be suppressed by setting hide_generator_header: true in tyk.conf (or using the equivalent environment variable).

• Standardizing Format: clients expect a specific error structure, such as RFC 7807 Problem Details, that the default response does not produce.
• Gateway Migration: clients may depend on error response formats from a previous API gateway that differ from Tyk’s defaults.
• Hiding Internal Detail: default messages might expose information about your authentication mechanism, key structure, or upstream topology.
• Consistency Across APIs: upstream services may return different error formats; normalizing them at the Gateway improves the client experience.
• Per-API Requirements: different APIs published on the same Gateway may need to return different error formats or status codes for the same underlying error condition.

​

Customization Mechanisms

​

How the Mechanisms Interact

• Authentication Error Configuration runs at Gateway startup, not at request time. Error Overrides and Response Body Overrides see the already-modified status codes and messages, not the original Tyk defaults.
• Error Overrides only bypasses Response Body Overrides when it provides a complete body. A rule that changes only the status code or message still falls through to the template for body formatting.
• The mechanisms can coexist. Error Overrides can be introduced incrementally: existing template files and override_messages settings continue to function for any error condition not covered by an override rule.

​

Error Overrides

​

Rule Structure

• an optional match object to specify which errors within that status code trigger the rule.
• a response object that defines what Tyk returns when the rule fires (in place of the original error response).

{
  "error_overrides": {
    "403": [                        // key: exact code ("403") or wildcard ("4xx")
      {
        "match": {                  // optional: specifies which errors trigger this rule
          "flag": "AKI"             // match by error classification flag
        },
        "response": {               // what Tyk returns when this rule fires
          "status_code": 401,       // new HTTP status code
          "headers": { "WWW-Authenticate": "Bearer" },        // headers to set in the response
          "body": "{\"error\": \"Authentication required\"}"  // response body
        }
      }
    ]
  }
}

​

Matching Criteria

​

Matching Gateway-generated errors

• If flag is set and matches, the rule fires.
• Otherwise, if messagePattern is set and matches the error message, the rule fires.
• If a match field is set but does not match, the rule does not fire.
• If neither field is set, the rule matches any error with that status code.

​

Matching Upstream-generated errors

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{"error": {"code": "OUT_OF_STOCK"}}

"match": {
  "flag": "URS",
  "bodyField": "error.code",
  "bodyValue": "OUT_OF_STOCK"
}

• Set flag=URS to match upstream 5xx responses only, excluding Gateway-generated errors with the same code (such as a circuit-breaker 503).
• To differentiate between different upstream 5xx errors, set bodyField/bodyValue or messagePattern to match on the response body. Note that messagePattern matches on the response body for upstream errors.

• flag=URS is 5xx-only. There is no flag that isolates upstream 4xx responses from Gateway-generated ones with the same status code.
• Use messagePattern to differentiate by content: for Gateway errors it matches against the error message string; for upstream errors it matches against the response body. A pattern that matches the upstream response format but not Tyk’s fixed error messages effectively targets upstream responses only.

​

Response Customization

• This is the HTTP status code to return to the client.
• Any valid HTTP status code is accepted.
• If omitted, the original error status code is preserved.
• Available as {{.statusCode}} in Go Template Syntax used in body or template.

• A JSON object of key-value string pairs to set on the response. These are merged into the existing response headers; any key you specify sets or overrides that header while all other headers remain intact.
• If omitted, no additional headers are set.
• To remove a header, include it in headers with an empty value.
• Note that the X-Generator header cannot be removed via override rules; suppress it globally using hide_generator_header.

• The error message text.
• Available as {{.Message}} in Go Template Syntax used in body or template.
• If omitted, {{.Message}} resolves to an empty string in the body or template.

• The response body, written verbatim to the client.
• Can be a static string or a Go template string (see Go Template Syntax).
• When body is provided, the legacy template system is bypassed entirely.
• If body is set, template is ignored.

• The base filename (without extension) of a file in the Gateway’s templates/ directory.
• The file content is used as the response body, written verbatim to the client.
• Tyk appends .json or .xml to the base filename based on the Content-Type of the original request.
  • For example, "my_error" resolves to templates/my_error.json for JSON requests and templates/my_error.xml for XML requests.
• Use template as an alternative to body when the template body is large or shared across multiple rules.

​

Partial Override

​

XML Clients

​

Go Template Syntax

• {{.StatusCode}}: The HTTP status code being returned.
• {{.Message}}: The error message text.

• {{.InvalidParams}}: A string describing the specific validation failure. Only available when flag=BIV (see Request Validation). Example: "body.age must be a positive integer".

"response": {
  "statusCode": 400,
  "headers": { "Content-Type": "application/problem+json" },
  "body": "{\"type\": \"https://example.com/probs/validation\", \"title\": \"Invalid Request\", \"status\": {{.StatusCode}}, \"detail\": \"{{.Message}}\"}"
}

​

Configuration

• Gateway-level configuration is applied to all APIs deployed on the Gateway
• API-level configuration applies to a specific API and is evaluated first

​

Gateway Level

"error_overrides": {
  "403": [{
    "match": {
      "flag": "AKI"
    },
    "response": {
      "status_code": 401,
      "headers": { "WWW-Authenticate": "Bearer" },
      "body": "{\"error\": \"Authentication required\"}"
    }
  }]
}

​

API Level

"x-tyk-api-gateway": {
  "errorOverrides": {
    "enabled": true,
    "value": {
      "403": [{
        "match": {
          "flag": "AKI"
        },
        "response": {
          "statusCode": 401,
          "headers": { "WWW-Authenticate": "Bearer" },
          "body": "{\"error\": \"Authentication required\"}"
        }
      }]
    }
  }
}

{
  "error_overrides_disabled": false,
  "error_overrides": {
    "403": [{
      "match": {
        "flag": "AKI"
      },
      "response": {
        "status_code": 401,
        "headers": { "WWW-Authenticate": "Bearer" },
        "body": "{\"error\": \"Authentication required\"}"
      }
    }]
  }
}

​

Flag Reference

​

Authentication and Authorization Errors

​

Request Validation Errors

​

Rate Limiting and Quota Errors

​

Upstream Connectivity Errors

​

TLS Errors

​

Upstream Error Responses

​

Response Body Overrides

• Gateway-Level Scope: The same customized response bodies are applied for all APIs on the Gateway.
• Upstream Errors: This method cannot intercept upstream errors.
• Status Code Scope: There is no way to differentiate between different errors that share the same status code.
• HTTP 404 Limitation: Response Body Overrides cannot be used to customize the body of HTTP 404 responses.
• Response Body Only: This method does not enable customization of status code, error message or headers.

​

Authentication Error Configuration

"override_messages": {
  "auth.key_not_found": {
    "code": 401,
    "message": "Invalid or missing API key"
  }
}

• Limited Scope: This method only works for specific auth-related errors.
• Gateway-Level Scope: The same responses are applied for all APIs on the Gateway.
• Limited Customization: This method does not enable customization of response body or headers.

​

Other Error Configurations

• Request Validation: When using Request Validation middleware, the HTTP status code returned in case of validation failure can be configured in the API definition.
• HMAC Signature Validation: The HMAC signature authentication middleware exposes fields that set the HTTP status code and error message returned when signature validation fails.
• Custom Plugins: JavaScript plugins and Rich Plugins can use the Return Overrides mechanism to halt middleware execution and return a custom HTTP response directly to the client. Go plugins can write directly to the http.ResponseWriter to terminate the request and return a fully custom status code, headers, and body.
• Virtual Endpoints: Virtual endpoints execute a JavaScript function that returns a fully custom response (status code, headers, and body) via the TykJsResponse() function.