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.
Limitations
This feature is 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.
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.