Introduction
Youʼre preparing to Flex with billions of REST requests on your flashy new Mulesoft Flex Gateway instance.
Among all the offerings of the platform, you planned to fully leverage OAS support with Schema Validation policy.
Wait a minute! As I write, on Feb 11, 2026, almost latest Flex Gateway version 1.11.4 features a major flaw on APIs instances based on a REST Exchange asset where 14 to 70 seconds of downtime occur for all the gatewayʼs proxies.
Sadly, latest version, 1.11.4 release notes doesnʼt bear any news about it.
Itʼs likely that SOAP support bears the same flaw.
Read on to find out impacted use case, root cause and how you can prevent recurrent downtimes on your application network.
Use case
After creating a REST Exchange entry with an OAS, you created an API Manager instance with Schema Validation to validate incoming requests against the OAS.
Then, you deployed this proxy and several others for your various usecases.
You publish a new version of the OAS on Exchange to add a useful query param. Then, you use Change API Specification functionality of API Manager entry configuration to use the new OAS version you just published.
Finally, you click Save & Apply in the settings section of the entry to apply the OAS update.
A new Flex Gateway instance will start with updated configuration and replace the previous one.
Your API validates the new query param. However, thousands of requests failed with 401, 404 and 503 error codes during the update on all requests to that proxy instance for a minute and your users are upset.
Letʼs get into the root cause.
Root cause
When updating the API specification version of an API Manager entry, new gateways instances are created to replace existing ones. Requests are routed to new instances before all API instance configurations are fully loaded.
503s occur on early stages of Schema Validation Policy loading.
401s occur when Client ID Enforcement Policy reloads and contracts werenʼt loaded yet.
404s occur when OAS is temporarily unavailable to Schema Validation Policy.
Alright, but how to fix it?
Only Mulesoft can fix it with an update to the product.
But hang on! We got something for you. We have solutions to propose to you in order to preserve your uptime. Weʼve labeled the section as workaround because youʼre not getting the OAS validations you deserve.
Workaround
To prevent downtimes on OAS updates, you should use HTTP assets as base for your API Manager entries.
The alternative is to deploy a REST asset without Schema Validation policy and never update the asset version on the API Manager entry. That would be misleading to viewers of the entries. However, should you expect the issue be fixed by Mulesoft soon and be fine with not touching the API spec version on the entries, that would allow you to enable OAS validation without recreating Exchange assets and API Manager instances.
You may think disabling the Schema Validation policy during the update would be enough to prevent the downtime but itʼs not the case. Activating Schema Validation policy on the API Manager instance will cause downtime.
A sign of hope
With our clientsʼ best interests in mind, weʼve opened a case to Mulesoft support and pushed hard to get this fixed. As a result, Mulesoft created known issue Salesforce Help to address this downtime.
We invite you to follow known issue Salesforce Help if youʼre planning to use Flex Gateway for REST APIs.
Our discussions with the Mulesoft Support let us hope that a new version of Flex Gateway will be released in February 2026 to prevent downtime on Flex Gateway API instances OAS updates.