Global external Application Load Balancers allow you
to customize your own error responses when an HTTP error status code (4xx
and
5xx
) is generated. You can customize error responses for errors generated by
both the load balancer and the backend instances. You can also customize error
responses for error response codes that are generated when traffic is denied by
Google Cloud Armor.
Here is an example of a custom error page where you can configure error responses for your external-facing consumer application with your own company branding and logo, links to related pages, and customized messaging.
By using a custom error response policy, you can configure different error responses for different HTTP error status codes, URL domains, URL paths, and HTTP request header and parameter fields.
Returning custom error responses helps you improve the experience for your users by offering the following benefits:
- Provides a consistent branding experience
- Provides contextual and relevant information to enhance usability and user experience
- Mitigates negative impact of downtime and client-side errors
- Improves network security
If you don't configure a custom error response policy, a generic non-branded error object is served, as shown in figure 2.
Use cases
The custom error response feature addresses many use cases. This section provides a few high-level examples.
Define your own maintenance page
You can return an error page with company branding and information when your backends are unhealthy or in maintenance mode. You can build contextual error pages that contain helpful information such as contact center phone numbers or when users should retry accessing the website. You have the option to customize error pages based on the matching of error conditions such as hostname and HTTP error code.
Define your own default error page
You can set up customized error responses by specific error codes. For
example, you can set up an error page with a "Login or register" message
for a 401 (Unauthorized)
HTTP response code. You can also set up a default error
page that contains company branding and other relevant information for all other
4xx
series and 5xx
series HTTP error codes.
Define error responses for security rules
You can return a custom error page for error response codes that are generated
when traffic is denied by Google Cloud Armor security policies. You need to ensure
that you configure the error page with the same 4xx
series or 5xx
series HTTP
error code that you entered in the Google Cloud Armor security rule.
Mitigate impact of downtime
When applicable, you can configure an error response to return a 200 (OK)
HTTP
status code and serve a static web page so that users see more contextual and
helpful information instead of an error page during the downtime.
Customize error responses based on client request type
You can customize an error response based on HTTP request headers and
parameters—for
example, the Content-Type
header. When routing the original request to the
error service, the routing can take into account the Content-Type
header to
serve either a web page (for requests from browsers) or JSON (for requests from
a web API).
How custom error response policies work
A custom error response policy can be defined at three levels of the URL map resource—the load balancer level, the URL domain level, and the URL path level.
Load balancer level. The policy is applied to all traffic received by the load balancer.
URL domain level. The policy is applied to traffic directed to a specific domain name or a hostname—for example,
www.example.com
.URL path level. The policy is applied to traffic directed to a specific path—for example,
www.example.com/images/*
. At this level, you can also use advanced match conditions with HTTP request headers and parameters—for example,Content-Type:application/json
.
The following table shows a custom error response policy applied at the load balancer level, the URL domain level, and the URL path level of the URL map.
Policy level | API field |
---|---|
Load balancer | urlMaps.defaultCustomErrorResponsePolicy |
URL domain | pathMatchers[].defaultCustomErrorResponsePolicy |
URL path |
|
If you configure a custom error response policy at multiple levels of the URL map resource, the error object specified by the custom error policy at the lowest level of the URL map is returned. Error response policies defined at a lower level of the URL map are more specific and take precedence over error response policies defined at a higher level of the URL map.
For example, a custom error response policy at the load balancer level is applied only if the policy matches the error conditions, and no matching policy has been defined for the error code at the lower levels—the URL domain or URL path. Similarly, a custom error response policy at the URL domain level is applied only if the policy matches the error conditions, and no matching policy has been defined for the error code at the lower level—the URL path. To learn more about this configuration, see Configure granular custom error response policies for different domains, paths, and error response codes.
Specify multiple error response rules to match HTTP error response codes
At any level within a custom error response policy, you can specify multiple error response rules. These rules can match an HTTP error response against specific error codes or a range of error codes. If you specify a rule for a range of error codes as well as rules for specific error codes, then rules with specific error codes take precedence.
For example, assume that you configure a rule for a 401 (Unauthorized)
error
code and another rule for all 4xx
series error codes. If the backend service
returns a 401
error code, then the rule that
matches the 401
error is applied. However, if the backend service returns a
403
error code, then the rule for 4xx
errors takes effect.
Override the HTTP response code
The error response rules let you modify the HTTP response code returned by
the load balancer. This essentially means that you can override the response
code generated by the server and define what the final response code for the
request should be. You can specify to return any HTTP response code, including
200 (OK)
, the 4xx
series or the 5xx
series of response codes, or any other
three-digit response code. To learn more about overriding the response code,
see Configure an error page for a specific error code for a specific
host.
If you define an override response code, it is captured as a new field
overrideResponseCodeServed
in the load balancing logs. This field
is populated only for those requests where an override response code is applied
by the custom error response policy.
The status
code logged in the httpRequest
field is not impacted.
It captures the HTTP response code generated by the server or the HTTP response
that the load balancer returns. This status code can be different from the
actual code served to the client if the response code is modified by a custom
error response policy.
Cache custom error responses
A custom error response can be cached by specifying a negative caching policy for the backend that generated the error. The reason to do this is to apply fine-grained control over caching for common errors or redirects. This can reduce the load on your origins and improve the end-user experience by reducing response latency.
A negative caching policy defined for the backend that generated the
error always take precedence over the Cache-Control
metadata defined for the
error object in the error service. Further, if an override response code is
returned by the load balancer, then a negative caching policy is applied based
on the value of the override response code and not based on the original
response code that the backend returned to the load balancer. If a non-error
code (HTTP 200
) is returned as an override response code, then a negative
caching policy does not apply.
If the time to live (TTL) for the failure response has not lapsed, the load balancer continues to serve cached content without routing the request to a backend service or a backend bucket. However, this behavior depends on whether Cloud CDN is enabled for your load balancer.
Cloud CDN is enabled for the load balancer
This section describes the behavior of the load balancer when Cloud CDN is enabled and custom error responses are used.
When a request is received by the load balancer, it checks the Cloud CDN cache. If the load balancer finds a cached response to the user's request, the load balancer returns the cached response to the user. This cached response can be either the user's requested content or a custom error object.
If there's a cache miss, the request is processed by the load balancer and sent to the backend.
If the backend serves a non-error response, that response is returned to the end user. However, if a client request encounters an error (a
4xx
or5xx
HTTP response code), the load balancer tries to get the custom error object from the error service that you specified in the following manner:The load balancer checks all custom error response policies and gets the appropriate path of the custom error object that corresponds with the error status code and other match conditions.
The load balancer forwards the request for the custom error object to the error service that you specified in the custom error response policy. The term error service refers to the backend bucket or the backend service that serves the custom error content.
The load balancer returns the custom error object to the client that made the request. It also sends the object to Cloud CDN for caching the error object for the amount of time specified by
cdnPolicy.negativeCachingPolicy[].ttl
.
Cloud CDN is disabled for the load balancer
If Cloud CDN is disabled, we recommend the use of a backend bucket as the error service and not a backend service. This is because a backend service cannot cache content if Cloud CDN is disabled; however, backend buckets have built-in caching capability and can cache error responses even if Cloud CDN is disabled.
Limitations
Custom error responses are supported only with the global external Application Load Balancer. Regional and classic modes are not supported.
If the custom error object can't be fetched from the error service—for example, if the content path is misconfigured—then a generic non-branded error object is served.
The custom error response policy does not monitor or filter the object returned by the error service for security risks. Thus, you should be diligent about eliminating vulnerabilities and limiting the impact of a potential exposure.
Custom error responses are supported only on publicly readable Cloud Storage buckets.
To prevent any misconfigurations while using a Cloud Storage bucket, review common best practices for Cloud Storage.
Pricing
There's no additional cost for using custom error responses. Standard pricing for Google Cloud load balancing is applicable. For more information, see Pricing.