For a better viewing experience of this article , we recommend that you download and view the attached pdf.

Introduction

The API Manager Fault Handler is designed to handle errors that may occur during transactions of user APIs published via API Manager. The capability allows users to customize the implementation of their own error handling; such as introduction of custom Security Policies and external integrations. For more details, please see Configure API Manager custom policies.

The below document outlines, the current design and implementation, followed by the issues and in some cases bugs that our clients have observed in the implementation. The document will then do a walk through of the changes implemented in the February 26 Release and the benefits these changes will bring. Finally, the document will provide a list of before and after worked examples to clearly outline the changes along with some Breaking Changes that users may see in their error handling flow.

Design and Implementation

The API Gateway via Policy Studio allows for the creation of REST APIs that are exposed on endpoints that, when hit, can trigger a policy flow, this is outlined in detail in Develop REST APIs in Policy Studio and Introduction to policies, with the API Gateway REST API Fault Handling implementation employing the out-of-box API Gateway policy fault handling workflow.

The API Manager policies workflow is an extension of this allowing for deeper and richer features; these include the well-known API flow options of Global Request, Global Response, API Request , API Response, Fault Hander Policy. Details on configuration of these policies can be found here: Configure API Manager custom policies.

Fig 1. Process of an API request processed at runtime by the API Manager

Fig 2. Detailed API Manager process flow

The API Manager Global Fault Handler; default or custom, is configured to process errors for a API request when an error or exception occurs during the API Manager runtime API invocation. An error is generally triggered in two scenarios; when a HTTP Error is generated or when a Back-end Service responds with non-2xx response code.

Fig 3. API Manager Fault handler scope

Known Issues

• With the enhanced complexity and feature set of API Manager, the policy execution flow between API Manager and API Gateway diverged. This divergence caused differences in the behaviour of API Manager's API Broker and API Gateway's REST APIs' API Broker. This led to successful messages displaying different Traffic Monitor filter execution flows and orders.
• A particular scenario of above; and the prime driver of this change, is in the case of Fault Handling invocation during the creation of API Service Contexts showing inconsistencies in Transaction and Traffic Monitor logging. This leads to incorrect and at times misleading representations of the transactions in the API Gateway Manager Traffic Monitor and API Gateway Analytics Metrics database. The error handling workflow in API Manager has multiple branches that handle possible ApiShunt errors differently depending on API Manager fault handler configuration. This complicates various areas such as; the test coverage, maintaining consistent error handling; and addressing reported issues.

• The customisation of the Fault Handling mechanism also shows scenarios with unexpected behaviour, for example, invoking fault handlers twice.
• OPTIONS requests processing in API Manager has incorrectly diverged from API Gateway in some cases. This contributed to the problems in Error Handling that is expected to be identical in API Gateway and API Manager. For example, incoming client CORS requests to API Manager, did not align with API Gateway.

Important Changes

The API Manager broker invocation has the following important changes:

• The API Broker policy execution path is now consistent and accurate
• Inbound Security custom policy fault handling will only invoke a fault handler defined in API Manager, matching the diagram Fig 3
• API Manager CORS request processing aligned with API Gateway CORS, responses are now more correctly inline with the RFC requirements

Benefits of the Change

The benefits to the customer for this change are;

• Consistency in the handling of errors between API manager and API Gateway policies workflow allowing API Analytics and Traffic Monitor correct presentation of transactions, API Broker policy execution path
  • Consistent execution filter paths, matching the flow shown on diagram Fig 1.
    • consistent level of the fault handler invocation
    • trivial parsing of the Traffic Monitor data
    • simple analysis of successes and failures in Traffic Monitor
      • always starts with single node "API Broker"

Fig 5. API Manager Fault Handler example where an error is triggered on a backend API response. Traffic Monitor now correctly indicates a single and unsuccessful API Broker transaction with Transaction Audit Message of Backend Error.

• Fault handlers always have access to the "api.error.source" and "api.error.reason" message attributes
  • see Fault handler generated errors

• Custom fault handlers can override the default final transaction status On-Demand
  • Please see for further details: Set response status filter
  • The status reflected in the API Gateway Manager Traffic Monitoring, Analytics Traffic Monitoring and API Manager Monitoring accordingly

• API Manager uses less memory footprint for API Broker circuits
• Accurate API Broker filters timing reflected in Traffic Monitor

Runtime Examples

API Broker Success and Failure Scenarios

Below are several examples showing success and failure scenarios along the difference in behavior in the Traffic Monitor Execution Path of API Manager and API Gateway Transactions before and after the February 2026 Release.

In the setup of these examples, the following was configured

• A default API Key Inbound Security Device where the application Id is 3bde5ea8-ff29-4f38-8fb5-29442716e260
• Custom Fault Handler that preserves the transaction status and the HTTP response code/status set by API Manager

API Manager Broker Invocation

API Shunt: n/a
Response: 200 OK
Changes:

• The API Broker now reports Transaction Audit Message as "Success"

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Error Trace	n/a	n/a
circuit.failure.reason	n/a	n/a
Transaction Audit Message	none	Success
Service Context	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":"healthcheck", "status":"success", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":14}	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":"healthcheck", "status":"success", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":20}

API Shunt: noMethodMatched
Response: 403 No Match For Request
Changes:

• The API Broker now accurately displays the execution time.
• API Broker now presents a consistent view of the filter names and their flows.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Trace	Filter that caused failure: No Match For Request Policy 'AI Broker' { Filter 'Set service context' Status: PASSED Filter 'No Match For Request' Status: FAILED } No Match For Request filter failed	Filter that caused failure: API Transaction Policy 'API Broker' { Filter 'API Transaction' Status: FAILED } API Transaction filter failed
circuit.failure.reason	No Match For Request filter failed	API Transaction filter failed
Transaction Audit Message	No Match For Request	No match found for request
Service Context	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":null, "status":"failure", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":9}	{"service":"My API test", "client":null, "method":null, "status":"failure", "monitor":true, "org":null, "app":null, "duration":5}

API Shunt: tooManyRequests
Response: 429 Too Many Requests
Changes:

• The API Broker now accurately displays the execution time.
• API Broker now presents a consistent view of the filter names and their flows.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Trace	Filter that caused failure: Too Many Requests Policy 'API Broker' { Filter 'Set service context' Status: PASSED Filter 'Too Many Requests' Status: FAILED } Too Many Requests filter failed	Filter that caused failure: API Transaction Policy 'API Broker' { Filter 'API Transaction' Status: FAILED } API Transaction filter failed
circuit.failure.reason	Too Many Requests filter failed	API Transaction filter failed
Transaction Audit Message	Too Many Requests	Too Many Requests
Service Context	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":"healthcheck", "status":"failure", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":11}	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":"healthcheck", "status":"failure", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":6}

API Shunt: allAuthNDevicesFailed
Response: 401 Security failure
Changes:

• The API Broker now accurately displays the execution time.
• API Broker now presents a consistent view of the filter names and their flows.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Trace	Filter that caused failure: Authentication Failure Policy 'API Broker' { Filter 'Set service context' Status: PASSED Filter 'Authentication Failure' Status: FAILED }Authentication Failure filter failed	Filter that caused failure: API Transaction Policy 'API Broker' { Filter 'API Transaction' Status: FAILED } API Transaction filter failed
circuit.failure.reason	Authentication Failure filter failed	API Transaction filter failed
Transaction Audit Message	Authentication Failure	Authentication Failure
Service Context	{"service":"My API test", "client":null, "method":"healthcheck", "status":"failure", "monitor":true, "org":null, "app":null, "duration":8}	{"service":"My API test", "client":null, "method":"healthcheck", "status":"failure", "monitor":true, "org":null, "app":null, "duration":10}

API Shunt: noApiMatched
Response: 403 No Match For Request
Changes:

• The API Broker now accurately displays the execution time.
• API Broker now presents a consistent view of the filter names and their flows.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Trace	Filter that caused failure: No Match For Request Policy 'AI Broker' { Filter 'Set service context' Status: PASSED Filter 'No Match For Request' Status: FAILED } No Match For Request filter failed	Filter that caused failure: API Transaction Policy 'API Broker' { Filter 'API Transaction' Status: FAILED } API Transaction filter failed
circuit.failure.reason	No Match For Request filter failed	API Transaction filter failed
Transaction Audit Message	No Match For Request	No match found for request
Service Context	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":null, "status":"failure", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":9}	{"service":"My API test", "client":null, "method":null, "status":"failure", "monitor":true, "org":null, "app":null, "duration":5}

API Shunt: backendError
Response: 400 Bad Request
Changes:

• The Service Context now reports the status accurately as a failure.
• Custom fault handlers can now override the transaction status to set it to "success" on demand by invoking the "Set Response Status" filter configured as "Pass", which makes sense when the HTTP response status is also set to 200 OK (by invoking the "HTTP Status Code" filter).
• The API Broker now accurately displays the execution time.
• PI Broker now presents a consistent view of the filter names and their flows.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Trace	Filter that caused failure: Backend Error Policy 'API Broker' { Filter 'Set service context' Status: PASSED Filter 'API Proxy' Status: PASSED Policy 'Default API Proxy Routing' { Filter 'Default Routing' Status: PASSED Filter 'not-required-here' Status: PASSED Policy 'Default Profile-based Routing' { Filter 'Connect to URL' Status: PASSED } } } Policy 'API Broker' { Filter 'Set service context' Status: PASSED Filter 'Backend Error' Status: FAILED } Backend Error filter failed	Filter that caused failure: Validate backend API response Policy 'API Broker' { Filter 'API Transaction' Status: FAILED Policy 'API method' { Filter 'Context Validation' Status: PASSED Filter 'API Proxy' Status: PASSED Policy 'Default API Proxy Routing' { Filter 'Default Routing' Status: PASSED Filter 'not-required-here' Status: PASSED Policy 'Default Profile-based Routing' { Filter 'Connect to URL' Status: PASSED } } Filter 'Validate backend API response' Status: FAILED } } Validate backend API response filter failed
circuit.failure.reason	Backend Error filter failed	Validate backend API response filter failed
Transaction Audit Message	Backend Error	Backend Error
Service Context	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":"400", "status":"success", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":31}	{"service":"My API test", "client":"3bde5ea8-ff29-4f38-8fb5-29442716e260", "method":"400", "status":"failure", "monitor":true, "org":"API Development", "app":"Test APP 1", "duration":75}

API Gateway REST API Broker Invocation

API Shunt: n/a
Response: 200 OK
Changes:

• The API Broker now reports Transaction Audit Message as "Success"
• The "Context Validation" filter is introduced for transparency of policy execution time and failures.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Source	Value	Value
Trace	n/a	n/a
circuit.failure.reason	n/a	n/a
Transaction Audit Message	Success in setting the message (*) (*) The message is not API specific, inconsistent and specific to a filter of current Routing policy. And depending on filter implementation it can be unset (e.g. see Reflect filter in the example above).	Success
Service Context	{"service":"My Test API", "client":null, "method":"healthcheck", "status":"success", "monitor":true, "org":null, "app":null, "duration":34}	{"service":"My Test API", "client":null, "method":"healthcheck", "status":"success", "monitor":true, "org":null, "app":null, "duration":2}

API Shunt: noMethodMatched
Response: 404 No match found for request
Changes:

• Clearer and standardized filter execution path when an error happened prior API method policy invocation.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Source	Value	Value
Trace	Filter that caused failure: No Match For Request Policy 'API Broker' { Filter 'Set service context' Status: PASSED Filter 'No Match For Request' Status: FAILED } No Match For Request filter failed	Filter that caused failure: API Transaction Policy 'API Broker' { Filter 'API Transaction' Status: FAILED } API Transaction filter failed
circuit.failure.reason	No Match For Request filter failed	API Transaction filter failed
Transaction Audit Message	No Match For Request	No match found for request
Service Context	n/a	n/a

API Shunt: invokableMethodParamFailure
Response: 400 Bad Request
Changes:

• Clearer and standardized filter execution path when an error happens during API method policy invocation.

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path
Source	Value	Value
Trace	Filter that caused failure: Bad Request Policy 'API Broker' { Filter 'Set service context' Status: PASSED Filter 'Bad Request' Status: FAILED } Bad Request filter failed	Filter that caused failure: Context Validation Policy 'API Broker' { Filter 'API Transaction' Status: FAILED Policy 'healthcheck' { Filter 'Set service context' Status: PASSED Filter 'Context Validation' Status: FAILED } } Context Validation filter failed
circuit.failure.reason	Bad Request filter failed	Context Validation filter failed
Transaction Audit Message	Bad Request	Bad Request
Service Context	{"service":"My Test API", "client":null, "method":"healthcheck", "status":"failure", "monitor":true, "org":null, "app":null, "duration":42}	{"service":"My Test API", "client":null, "method":"healthcheck", "status":"failure", "monitor":true, "org":null, "app":null, "duration":34}

Scenarios when API Broker's process CORS Requests

This section describes the differences processing API Manager and API Gateway CORS requests by API Broker

Default API Key inbound security is configured.

API Manager REST API with default CORS profile configuration

• OPTIONS request to existing API method

ApiShunt: optionsRequest
Http Request CORS Headers: none
Changes:

• The new API Broker meets OPTIONS request defined by RFC 9110

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path	The filter execution path is unavailable
Source	Value	Value
Response	200 OK Allow: GET, HEAD, OPTIONS Content-Type: text/plain	204 No Content Allow: GET, HEAD, OPTIONS
Error Trace	n/a	n/a
circuit.failure.reason	n/a	n/a
Transaction Audit Message	unavailable	Options Request
Service Context	unavailable	{"service":"My API test", "client":null, "method":"healthcheck", "status":"success", "monitor":true, "org":null, "app":null, "duration":2}
Transaction Status	unavailable	Pass

ApiShunt: optionsRequest
Http Request CORS Headers: Origin: https://localhost:8065/
Changes:

• The new API Broker meets OPTIONS request defined by RFC 7231

	Pre February 26 Release	Post February 26 Release
TM Filter Execution Path	The filter execution path is unavailable
Source	Value	Value
Response	200 OK Allow: GET, HEAD, OPTIONS Content-Type: text/plain	200 OK Allow: GET, HEAD, OPTIONS Content-Length: 0
Error Trace	n/a	n/a
circuit.failure.reason	n/a	n/a
Transaction Audit Message	unavailable	Options Request
Service Context	unavailable	{"service":"My API test", "client":null, "method":"healthcheck", "status":"success", "monitor":true, "org":null, "app":null, "duration":2}
Transaction Status	unavailable	Pass

API Gateway REST API with CORS profile configuration

• CORS profile configuration - Origin is *
• OPTIONS request to existing API method exhibit no change in behaviour

*Axway can and will update this page with further examples upon client feedback