This document provides example configurations of custom error responses. Before
you configure a custom error response, read the Custom error response overview.
The example configurations described on this page configure a custom error
response policy at three levels of the URL map resource—the load balancer
level, the URL domain level, and the URL path level.
The example configurations draw on concepts and build
on setups described in the following documents:
In this example, requests to the load balancer are routed to the backend service
named web-backend-service. If the request encounters a 4xx response, the
custom error response policy is configured to then send the request to the
error service, and an error object (not-found.html) is returned to the client.
To create a custom error response policy, follow these steps:
Upload the HTML error page (not-found.html) to the Cloud Storage bucket.
Edit web-map-http.yaml to add a custom error response policy as highlighted
in the following YAML configuration, in the
defaultCustomErrorResponsePolicy section. In this example, an error
response policy is configured at the load balancer level
(urlMaps.defaultCustomErrorResponsePolicy).
We recommend that you store all your error objects in a Cloud Storage
bucket and have them referenced by a backend bucket attached to your load
balancer. Cloud Storage buckets provide a simple way for you to store
your error objects and have them returned to your clients by using the load
balancer. However,
you can also serve error pages and related assets without using a backend
bucket. For example, you can use a backend service, which references a VM
instance group backend that has an Apache server configured to serve a custom
error response page.
Update the URL map by importing the latest configuration from web-map-http.yaml.
The error content from not-found.html is served and an HTTP 404 status code
is returned.
Example 2: Configure an error page for a specific error code for a specific host
This example builds on the previous example—Configure an error page for
all 4xx errors common to all hosts. It assumes that a load
balancer is already configured such that requests to the host
video.example.com are routed to the backend service named
video-backend-service. If a request fails authorization by the backend
service, the service returns a 401 (Unauthorized) response. The custom error
response policy is configured to then send the request to the error service, and
an error object (video-obtain-authorization.html) is returned to the client.
In most cases, your error content is likely to contain links to assets—for
example, a logo image. The client makes requests for assets referenced in the
error page, and additional requests are sent to the load balancer to fetch them.
The load balancer then responds to the request and returns the linked assets.
This is accomplished by storing these assets in the same backend bucket
specified in defaultCustomErrorResponsePolicy and adding a rule to route
requests from asset URLs (for example, /assets/logo.svg) to the backend
bucket. The load balancer's response to the request for linked assets is not an
error response, but a normal response, as shown in the following configuration.
The policy also lets you define what the final response code for the request
should be. In this example, the response code has changed from 401 to 200
by specifying the value of overrideResponseCode to 200. For all other 4xx
errors, the error content in not-found.html is returned to the client, and the
original HTTP response code from the backend service is preserved.
As shown in the following table, two custom error response policies are
configured in this example. These policies are created at the load balancer
level and the URL domain level.
Policy level
API field
Match HTTP response code
Error service
Error object returned
URL domain
pathMatchers[].defaultCustomErrorResponsePolicy
401
CUSTOM_ERRORS_BUCKET
video-obtain-authorization.html
Load balancer
urlMaps.defaultCustomErrorResponsePolicy
All 4xx
CUSTOM_ERRORS_BUCKET
not-found.html
To create a custom error response policy for a 401 error code for the host
video.example.com, follow these steps:
Upload the HTML error page (video-obtain-authorization.html) and related
assets (logo.svg) to the Cloud Storage bucket.
Edit web-map-http.yaml to add a custom error response policy as highlighted
in the following YAML configuration, in the
defaultCustomErrorResponsePolicy section. In this example, a custom error
response policy is configured at the load balancer level
(urlMaps.defaultCustomErrorResponsePolicy) and the URL domain level
(pathMatchers[].defaultCustomErrorResponsePolicy).
Because the error service is not defined at the URL domain level, the error
service at the URL domain level defaults to the error service defined at the
higher level; that is, the load balancer level.
creationTimestamp: '2020-01-14T19:12:44.680-08:00'
defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-service
defaultCustomErrorResponsePolicy:
errorResponseRules:
- matchResponseCodes:
- 4xx
path: '/not-found.html'
errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
fingerprint: d0eJJpCBpHg=
hostRules:
- hosts:
- video.example.com
pathMatcher: path-matcher-1
kind: compute#urlMap
name: web-map-http
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http
pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-backend-service
name: path-matcher-1
defaultCustomErrorResponsePolicy:
errorResponseRules:
- matchResponseCodes:
- 401
path: "/video-obtain-authorization.html
overrideResponseCode: 200
// The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the
// error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.
// A URL map path rule to route requests from asset URLs (for example, "/assets/logo.svg") to the backend bucket.
pathRules:
- service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET
paths:
- /assets
Update the URL map by importing the latest configuration from
web-map-http.yaml.
You have configured two backend buckets named BUCKET_1 and BUCKET_2 to
return the custom error pages.
As shown in the following table, four custom error response policies are
configured in this example. These policies are created across three
levels in the following order of precedence:
The 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; that is, the URL domain or the URL path.
Similarly, the 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; that is, the URL path. In this
example, if a request to the URL www.example.net/video/hd encounters a 404
response, then the file not-found-hd-videos-404.html is returned. However, if
a 404 response is encountered for a request to the URL www.example.net/video/,
then the file example-net-4xx.html is returned.
To create custom error response policies across three levels of the URL map,
follow these steps:
Upload the error objects to the Cloud Storage buckets.
Edit video-org-url-map.yaml to add custom error response policies as
highlighted in the following YAML configuration, in the
defaultCustomErrorResponsePolicy section.
Because the error service is not defined at the URL domain level, the error
service at the URL domain level defaults to the error service defined at the
higher level; that is, the load balancer level.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025年10月24日 UTC."],[],[]]
