Fix 505 http version not supported on API Gateway

Quick Answer: The "505 HTTP Version Not Supported" error on API Gateway indicates the client's HTTP request version (e.g., HTTP/3) is not supported by the API Gateway or its downstream service. Most likely, a misconfiguration or an unsupported client protocol is the cause. First, inspect the client's request headers, specifically the `Via` or `X-Forwarded-For` headers, and the `User-Agent` to identify the client and its HTTP version. Expect to find a client attempting to use HTTP/3 (QUIC) when the gateway or backend only supports HTTP/1.1 or HTTP/2.

What Causes This Error

• Client attempting to use an unsupported HTTP protocol version (e.g., HTTP/3 QUIC) that the API Gateway or its immediate upstream/downstream service does not recognize or support.
• API Gateway configuration explicitly restricts or does not enable newer HTTP versions, while the client is configured to prefer them.
• Intermediate proxies, load balancers, or firewalls between the client and API Gateway are stripping or altering HTTP version information, or only support older protocols.
• Backend service behind the API Gateway rejects HTTP requests with versions it doesn't support, and the gateway is transparently passing the client's original HTTP version.
• Misconfigured client-side HTTP library or tool (e.g., `curl` with `--http3` flag) forcing an unsupported protocol version.

Step-by-Step Fixes

Fix 1: Configure API Gateway to Support Desired HTTP Versions

Access your API Gateway's configuration console (e.g., AWS API Gateway, Azure API Management, NGINX Plus).,Navigate to the endpoint or listener settings for the affected API.,Locate the protocol settings and ensure that the desired HTTP versions (e.g., HTTP/1.1, HTTP/2) are explicitly enabled. For AWS API Gateway, this is often managed by the underlying Load Balancer (ALB) or CloudFront distribution, where you'd select 'HTTP/1.1', 'HTTP/2', or 'HTTP/2 and HTTP/1.1'.,Save the configuration changes and redeploy the API Gateway if necessary.,Test with the problematic client to verify the issue is resolved.

Fix 2: Adjust Client HTTP Protocol Preference

Identify the client application or tool making the request (e.g., web browser, `curl`, custom application).,If using `curl`, remove any flags like `--http2`, `--http3`, or `--quic` that force a specific protocol, allowing it to negotiate. Alternatively, explicitly set to a supported version like `--http1.1`.,For custom applications, review the HTTP client library's configuration. For example, in Java's `HttpClient`, ensure `version(Version.HTTP_1_1)` or `version(Version.HTTP_2)` is used, or allow default negotiation.,For web browsers, check browser settings or extensions that might force specific protocol versions (less common for 505 errors, but possible).,Retest the client request against the API Gateway.

Fix 3: Inspect and Configure Intermediate Proxies/Load Balancers

Identify any load balancers (e.g., AWS ALB, NGINX, HAProxy) or reverse proxies between the client and the API Gateway.,Access the configuration of these intermediate components.,Verify their listener/frontend protocol settings. Ensure they support and are configured to pass through or upgrade/downgrade HTTP versions appropriately (e.g., ALB 'Protocol version' setting).,Check for any protocol translation or stripping rules that might be inadvertently causing the 505 error.,Apply necessary changes and monitor traffic logs for successful protocol negotiation.

Fix 4: Verify Backend Service HTTP Version Support

Determine if the API Gateway is simply proxying the client's HTTP version directly to a backend service.,Access the configuration of the backend service (e.g., web server like NGINX, Apache, or application server).,Check the backend's server configuration for supported HTTP protocol versions. Ensure it explicitly supports HTTP/1.1 and/or HTTP/2.,If the backend does not support the client's preferred version, either configure the API Gateway to downgrade the request (if possible) or update the backend service's configuration.,Restart the backend service if configuration changes were made and retest the API call.

Advanced Fixes

Advanced Fix 1: Implement Protocol Downgrade/Upgrade at Edge (CloudFront/CDN)

If using a CDN like AWS CloudFront in front of your API Gateway, configure its viewer protocol policy to 'Redirect HTTP to HTTPS' and 'HTTPS Only'.,Set the 'Allowed HTTP Methods' and 'Cached HTTP Methods' appropriately.,Crucially, configure the 'Origin Protocol Policy' for your API Gateway origin. Choose 'Match Viewer' if your gateway supports all viewer protocols, or 'HTTPS Only' if you want CloudFront to handle protocol negotiation and forward a consistent HTTPS/HTTP/2 request to your gateway, effectively abstracting client protocol versions.,Deploy the CloudFront distribution changes and test the client request.

FAQs

Q: What does 'HTTP Version Not Supported' specifically mean in the context of an API Gateway?

A: It means the API Gateway, or a component it relies on, received an HTTP request using a protocol version (e.g., HTTP/3) that it does not recognize or is not configured to handle. The gateway expects a specific set of HTTP versions, typically HTTP/1.1 or HTTP/2, and rejects any request outside that range.

Q: Can a firewall or proxy cause a 505 error?

A: Yes, an intermediate firewall or proxy can cause a 505 error. If a proxy only supports older HTTP versions (e.g., HTTP/1.0 or HTTP/1.1) and a client sends an HTTP/2 or HTTP/3 request, the proxy might either reject it outright or mangle the request in a way that the API Gateway interprets as an unsupported version, leading to a 505 response.

Q: How can I check which HTTP version my client is using?

A: You can check the HTTP version your client is using by inspecting the request headers. For `curl`, use `curl -v <URL>` to see the protocol used. For browsers, use the browser's developer tools (Network tab) to inspect the request details. Look for the `Request Headers` section or the `Protocol` column, which will typically show `HTTP/1.1`, `HTTP/2`, or `h3` (for HTTP/3).

Q: Is HTTP/3 (QUIC) support common on API Gateways?

A: HTTP/3 (QUIC) support is becoming more prevalent but is not universally enabled by default on all API Gateway solutions or their underlying infrastructure. Many cloud providers offer HTTP/3 support through their CDN (e.g., CloudFront) or load balancer services, which can front an API Gateway. Direct HTTP/3 support on the gateway itself might require specific configuration or be a newer feature.

Related Errors