Custom error response overview

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.

Custom HTTP error response page.
Custom HTTP error response page

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.

Generic HTTP error response page.
Generic HTTP error response page

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

pathMatchers[].pathRules[].customErrorResponsePolicy

pathMatchers[].routeRules[].customErrorResponsePolicy

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.

  1. 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.

  2. If there's a cache miss, the request is processed by the load balancer and sent to the backend.

  3. 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 or 5xx HTTP response code), the load balancer tries to get the custom error object from the error service that you specified in the following manner:

    1. 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.

    2. 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.

    3. 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.

  • Custom error responses don't work if your global external Application Load Balancer only has backend buckets. You must have at least one backend service also attached to the load balancer, in addition to the backend bucket.

  • Any custom response headers defined based on the source of the custom error response are not applied to outgoing responses.

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.

What's next