All Products
Search

This Product

    API Gateway:Frequently asked questions

    Document Center

    API Gateway:Frequently asked questions

    Last Updated:Jun 26, 2026

    This topic answers frequently asked questions (FAQs) about Cloud-native API Gateway.

    Does Cloud-native API Gateway support IPv6?

    Yes.

    Does Cloud-native API Gateway support the x-forwarded-for request header?

    Yes.

    If a request includes the x-forwarded-for request header, the gateway appends the IP address of the previous hop. If the header is not present, the gateway adds it with the IP address of the previous hop.

    Note

    Spring Boot's embedded Tomcat removes the last IP address from the x-forwarded-for header by default. To prevent this, add the configuration server.forward-headers-strategy=none to your Spring Boot application.

    Resolving "upstream connect error or disconnect/reset header" errors

    This error indicates that the security group of the backend service is blocking access from the gateway instance.

    To resolve this, go to the Overview page of your gateway instance, click the Security Group Authorizations tab, and then click Add Security Group Rule to add a security group configuration. The gateway forwards requests directly to the Pod IP address in ACK, so you must open the port used by the pod in the security group rule.

    Using a header to match a domain name

    Add a request header matching rule when you create a route.

    Set the header field name to :authority and the header value to the specific domain name.

    Resolving request failures due to a large body

    This issue occurs because the gateway's connection buffer is too small. You can increase the buffer size:

    • If you use HTTP/1.x: Adjust the DownstreamConnectionBufferLimits parameter in the console.

    • If you use HTTP/2: Adjust the DownstreamConnectionBufferLimits and InitialStreamWindowSize parameters in the console.

    Limits on adding service sources

    • A single gateway instance can be associated with up to three ACK clusters.

    • A single gateway instance can be associated with only one Nacos instance.

    Cannot select an existing Nacos or ACK service source

    Cloud-native API Gateway can only add Nacos instances or ACK clusters that are in the same VPC. Adding service sources from different VPCs is not supported.

    Does Cloud-native API Gateway support custom HTTPS certificates?

    Cloud-native API Gateway does not host certificates. Instead, it pulls them from Alibaba Cloud Certificate Management Service. You can upload your own certificate to Certificate Management Service and then configure it for the domain name in the gateway.

    Effects of changing parameters on existing traffic

    • Changes to XffTrustedNum require a gateway restart to take effect.

    • Changes to UpstreamIdleTimeout cause upstream connections to disconnect and reconnect.

    • Changes to DownstreamIdleTime cause downstream connections to disconnect and reconnect.

    Abnormal health check status for a backend service

    An abnormal health check status can indicate several issues:

    • For a private service within a VPC, check if the security group of the backend service allows the gateway to access the required port. For more information, see Add a security group rule.

    • For a public-facing service, check if the VPC has Internet access. You can use the SNAT feature of an Internet NAT gateway to access the Internet. For more information, see Use the SNAT feature of an Internet NAT gateway to access the Internet.

    • For HTTP-based health checks, ensure that the request path and request domain are configured correctly.

    • For HTTP-based health checks, if the backend service's health check endpoint must be accessed over HTTPS, set the service's policy to TLS mode in Policy Configuration.

    • For HTTP-based health checks, if all the above configurations are correct, the issue might be that the health check interval is the same as the backend service's connection keep-alive time. Try increasing the health check interval.

    Determining the cause of a request error

    • Check if the response header contains x-envoy-upstream-service-time. If it does, the gateway has already forwarded the request to the backend service. The error likely originates from the backend service.

    • Check if the upstream_service_time field in the gateway's access log is empty. If the field is not empty, the gateway has already forwarded the request to the backend service. The error likely originates from the backend service.

    Updated HTTPS certificate does not take effect

    This issue typically occurs if an HTTPS certificate is also configured on a service that precedes the gateway, such as CLB, DCDN, WAF, or Anti-DDoS Proxy service. Check if the HTTPS certificate on the preceding node has also been updated. As a best practice, configure HTTPS certificates in only one place. If DCDN or WAF is deployed upstream from your gateway, you can configure HTTPS only on DCDN or WAF and configure the gateway to use HTTP for back-to-origin requests.

    Route prioritization

    On the Route Settings page of a gateway instance, the order of the routes in the list represents their matching priority, from highest to lowest. Priority is determined by the domain and the route rules. Domain matching priority is exact domain name > wildcard domain name. For example, test.example.com has a higher priority than *.example.com. For the same domain, path matching priority is Exact Match>Prefix Match>Match Regular Expression. For the same domain and path, rules with more matching conditions have a higher priority than those with fewer matching conditions (matching conditions include Header and Query parameters).

    HTTPS request failures with DCDN

    This issue typically occurs because DCDN does not include a Server Name Indication (SNI) in its back-to-origin requests to the gateway. To resolve this, configure the back-to-origin SNI in your DCDN settings.

    HTTPS request failures with WAF

    This issue typically occurs because WAF does not include a Server Name Indication (SNI) in its back-to-origin requests to the gateway. If you are using CNAME access mode in WAF, modify the settings for the corresponding domain. In the Enter Your Website Information step, select Enable Origin SNI.

    Does Cloud-native API Gateway support WebSocket?

    Yes, WebSocket is supported and enabled by default.

    Does Cloud-native API Gateway support gRPC?

    Yes. gRPC uses the HTTP/2 protocol for transport. Ensure that EnableHttp2 = true is set on the Parameter Settings page of the gateway.

    Does Cloud-native API Gateway support GZIP decompression?

    Yes. Ensure that EnableGzip = true is set on the Parameter Settings page of the gateway. Supported compression algorithms are Gzip and Brotli, which you configure using the ZipAlgorithm parameter. The default value is Gzip.

    Preserving header case

    Yes. Ensure that PreserveHeaderFormat = true is set on the Parameter Settings page of the gateway. This parameter applies only to HTTP/1.0 and HTTP/1.1. The HTTP/2 protocol specification requires all request and response headers to be in lowercase.

    Does Cloud-native API Gateway support HTTP/3?

    Yes. Ensure that EnableHttp3 = true is set on the Parameter Settings page of the gateway.

    Headers are converted to lowercase

    By default, the gateway converts all request and response headers to lowercase. To preserve the original case, set PreserveHeaderFormat = true on the Parameter Settings page of the gateway.

    Requests to a DNS domain service fail

    If the configured DNS domain is a public domain, you must configure SNAT in an Internet NAT gateway to allow the gateway to access the internet. By default, a gateway instance cannot access the internet.

    Missing trace information in the ARMS console

    Check if the EnableGenerateRequestId parameter is set to true in the gateway configuration. If it is set to false, you must add a compliant x-request-id header to your requests. Otherwise, the gateway cannot report trace information.

    Receiving a 400 error

    This error is typically caused by one of the following reasons:

    • The client sent a request with a protocol error. Check the gateway's access log for response_flags = DPE.

    • The backend service returned a 400 error. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 400 error. The upstream_host value is the IP address of the backend service that received the request.

    Receiving a 401 error

    This error is typically caused by one of the following reasons:

    • The gateway returned the error, indicating missing access credentials. Check if you have enabled authentication, authorization, or a WebAssembly plug-in.

    • The backend service returned a 401 error. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 401 error. The upstream_host value is the IP address of the backend service that received the request.

    Receiving a 403 error

    This error is typically caused by one of the following reasons:

    • The gateway returned the error, indicating insufficient access permissions. Check if you have enabled an IP address blacklist or whitelist, authentication, authorization, or a WebAssembly plug-in.

    • The backend service returned a 403 error. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 403 error. The upstream_host value is the IP address of the backend service that received the request.

    Receiving a 404 error

    This error is typically caused by one of the following reasons:

    • A matching route rule is not configured in the gateway. Check the gateway's access log. If the log contains response_flags = NR, it indicates that no route was found.

    • The backend service returned a 404 error. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 404 error. The upstream_host value is the IP address of the backend service that received the request.

    Receiving a 405 error

    If WAF protection is enabled, the request may have triggered a WAF protection rule. In this case, WAF returns the 405 status code.

    Receiving a 413 error

    This error is typically caused by one of the following reasons:

    • The request size exceeds the gateway's connection buffer limit. Increase the value of the DownstreamConnectionBufferLimits parameter on the Parameter Settings page.

    • The backend service returned a 413 error. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 413 error. The upstream_host value is the IP address of the backend service that received the request.

    Receiving a 429 error

    A gateway throttling rule was triggered. Check the gateway's access log. If the log contains response_flags = RL, review your gateway throttling rule.

    Receiving a 502 error

    This error is typically caused by one of the following reasons:

    • The backend service returned a response with a protocol error. Check the gateway's access log. If the log contains response_flags = UPE, the most common cause is a duplicate Transfer-Encoding field in the response header from the backend service. Check your backend service.

    • The backend service returned a 502 error. Check the gateway's access log. If the response_flags field is empty and the upstream_host field has a value, this indicates that the backend service returned the 502 error. The upstream_host value is the IP address of the backend service that received the request.

    Receiving a 503 error

    This error can be caused by the following reasons:

    • The target service specified in the route rule has no healthy IP addresses. Check the gateway's access log. This situation is indicated by response_flags = UH.

    • The backend service closed the connection while the gateway was forwarding the request. Check the gateway's access log. This situation is indicated by response_flags = UC. This is often because the connection idle timeout of the backend service is less than the gateway's UpstreamIdleTimeout value. Decrease the UpstreamIdleTimeout value on the Parameter Settings page of the gateway.

    • The gateway cannot connect to the backend service's IP address. Check the gateway's access log. This situation is indicated by response_flags = UF or response_flags = URX. This often occurs because the backend service's security group blocks access from the gateway. Check whether the security group of the backend service has been configured to allow the gateway to access the port. For more information, see Add a security group rule.

    • The backend service does not exist in the gateway's configuration. Check the gateway's access log. This situation is indicated by response_flags = NC. This can happen for several reasons:

      • The corresponding service no longer exists.

      • If the backend service has multiple ports, you must select a fixed port, not a dynamic port, when you configure the target service in the route.

      • A fixed port was selected for the backend service, but the service's port has changed.

    • The backend service returned a 503 error. If the response_flags field in the log is empty and the upstream_host field is not empty, this indicates that the backend service returned the 503 error. The upstream_host value is the IP address of the backend service that received the request.

    response_code is 0 in the access log

    A response_code of 0 in the access log indicates that the client did not receive a response code.

    This can happen for two main reasons:

    • The client closed the connection prematurely. This can happen, for example, if the client is on a weak mobile network or if the backend response is too slow. This is indicated when the response_flags field in the access log is "DC".

    • An HTTPS request was sent without a Server Name Indication (SNI), and no HTTPS certificate was configured for a wildcard domain. SNI is a TLS extension used to carry domain name information. This is indicated when the requested_server_name field in the access log is empty.

    Public traffic consumption by unmatched route requests

    Yes. All requests that pass through the gateway, including those that do not match a route, consume public traffic. Even if a request does not match any route rule, the gateway still consumes traffic to receive the request and send a response.

    You can check the traffic consumption in the gateway's access log using the following fields:

    • bytes_received: The size of the request body, representing inbound traffic.

    • bytes_sent: The size of the response body, representing outbound traffic.

    Requests that do not match a route are identified in the access log by a response_code_details value of route_not_found and a response_flags value of NR.

    Tracing the source of unmatched route requests

    After you enable log delivery for the gateway, you can query for requests that did not match a route in Log Service and use the log fields to identify the source IP address. The access log records all requests that pass through the gateway, including failed requests. The source IP address is in the downstream_remote_address field.

    In Log Service, run the following query to filter for requests that did not match a route:

    response_code_details: "route_not_found"

    In the query results, check the following fields to identify the request source:

    • downstream_remote_address: The address of the client that connected to the gateway.

    • x-forwarded-for: The x-forwarded-for field from the HTTP request header, which indicates the original source IP address of the request. If the request passes through proxies, this field may contain multiple IP addresses. The last IP address is the address of the previous hop before the gateway.

    To calculate the traffic consumption of these abnormal requests, run the following query in Log Service:

    response_code_details: "route_not_found" | SELECT sum(bytes_sent + bytes_received) AS total_bytes