Why does a request that works on the deprecated gateway return an error on the new one?

When I send identical requests to the deprecated gateway and to the new one, I get the expected "200 Success" response from the old one but "403 Forbidden" from the new one. What has changed?

While there are a number of subtle differences between the gateways that may result in different responses to identical requests, the most likely cause for unexpected error responses is the increased coverage and precision of AWS' Web Application Firewall (WAFV2). We've dialed back some of its restrictions to allow for a less troublesome transition, but it effectively enforces best practices that we all should already be following, so you may see some gotchas.

One you're likely to run up against has to do with user agents. A "User-Agent" request header lets the platform receiving your call identify the operating system, application, vendor, and/or version of the agent that created the request, and is often used to tailor the response as needed for that agent. According to RFC 9110 on HTTP Semantics, "A user agent SHOULD send a User-Agent header field in each request..." 

The deprecated gateway was configured more forgivingly and did not require a "User-Agent" request header, but the new one does to help sniff out "bad bots" and such. Web browsers, Postman, curl, and most language specific HTTP request libraries are set to include them by default, but you should check to make sure your application is following that convention. If you find you need to add one yourself, you should follow IETF HTTP Working Group guidelines which state that the value should be in the form "product_name/product_version" (e.g., "ACME-http_get/2.3"), but the gateway just requires a non-null value, so "*/*" will do. 

Another case we've seen quite a bit is that using outdated versions of HTTP request libraries can result in "403 Forbidden" error replies. Make sure you keep all your libraries as up-to-date as possible (not just to keep the AWS WAFV2 happy, but also to comply with UC's IS-3 Electronic Information Security policy). 

Finally, we've found an unexpected flaw in the deprecated gateway that we will not be replicating on the new one: it turns out you could use either "app-id" or "app_id" (i.e., with a hyphen or an underscore) as the header name when authenticating via headers parameters. On the new gateway you must use the underscore.