Serve custom error pages

You upload an HTML asset and attach it to an error status on a group.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• An HTTP group and a controlled origin response that returns an error status.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
ERROR_PAGE_ASSET_ID	Returned resource identifier, or your selected scope identifier.
GROUP_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'ERROR_PAGE_ASSET_ID: ' ERROR_PAGE_ASSET_ID
export ERROR_PAGE_ASSET_ID

Steps

1. Upload a static HTML page.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/error-page-assets" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"name":"unavailable","body":"<!doctype html><html><body><h1>Please try again later</h1></body></html>","contentType":"text/html; charset=utf-8"}'

   API reference: Create a new reusable custom error page asset

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "data": {
       "errorPageAssetId": 1
     }
   }

   Set ERROR_PAGE_ASSET_ID to the returned errorPageAssetId.

2. Match 5xx responses and preserve the original status.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/error-page-rules" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'statusMatch': '5xx', 'errorPageAssetId': int(os.environ['ERROR_PAGE_ASSET_ID']), 'isDisabled': False}))
   PYBODY

   API reference: Create a custom error page rule for an HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "errorPageRuleId": 1
     }
   }

3. Read the rule.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/error-page-rules" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: List custom error page rules for an HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

Verify

Trigger the controlled 5xx response. Confirm the HTML body is your asset and the original status is preserved. If you set responseStatusCode, compare the final response with that replacement status. Earlier TLS or front-end failures can occur outside custom error-page handling.

Use your configured site domain in this traffic check:

curl --silent --show-error --include "https://example.com/"

Expected: the site behavior described above. The application response body and status depend on your origin and selected policies.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

Troubleshooting

Symptom	Cause	Fix
Wrong page appears	A more specific scoped rule wins	Check route exact status, route class, group exact status, then group class, in that order.
Status changes unexpectedly	responseStatusCode replaces it	Remove the replacement to preserve the original status.
No custom page appears	Rule is disabled or failure happens before this response path	Check enabled state and reproduce an origin error.

Limits and defaults

Setting	Limit or default
HTML asset body	1 to 131072 UTF-8 bytes
Content type	Only text/html; charset=utf-8; also the default
Status matches	Exact 400 to 599, 4xx or 5xx
Replacement status	400 to 599; null preserves the original
Rule disabled	Default false

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
409	Resource state conflicts with the operation.
500	The request encounters a server error.

Related API operations

• DELETE /error-page-assets/{errorPageAssetId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/error-page-rules/{errorPageRuleId}
• DELETE /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/error-page-rules/{errorPageRuleId}
• GET /error-page-assets
• GET /error-page-assets/{errorPageAssetId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/error-page-rules
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/error-page-rules/{errorPageRuleId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/error-page-rules
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/error-page-rules/{errorPageRuleId}
• PATCH /error-page-assets/{errorPageAssetId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/error-page-rules/{errorPageRuleId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/error-page-rules/{errorPageRuleId}
• POST /error-page-assets
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/error-page-rules
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/error-page-rules

API reference

• Delete a custom error page asset

• Delete a custom error page rule from an HTTP group

• Delete a custom error page rule from an HTTP route

• List custom error page assets

• Get custom error page asset

• List custom error page rules for an HTTP group

• Get a custom error page rule for an HTTP group

• List custom error page rules for an HTTP route

• Get a custom error page rule for an HTTP route

• Update a custom error page asset

• Update a custom error page rule for an HTTP group

• Update a custom error page rule for an HTTP route

• Create a new reusable custom error page asset

• Create a custom error page rule for an HTTP group

• Create a custom error page rule for an HTTP route

• Groups and Routes

• Error Page Assets

Need Help?

Contact your account manager or use the Balancer portal.