Error responses

Customize eligible failures generated by the edge while preserving their status codes. Choose an error mapping when the edge has already produced an error; choose a direct response when a route should deliberately answer a request without forwarding it.

The response producer and body supplier are separate: the edge produces an eligible status, and more_option.custom_errors supplies its body. Application-generated errors kept their application bodies in the measured examples.

Choose a class or exact mapping

Mapping key	Applies to	Precedence
3, 4, 5	Eligible responses in the 3xx, 4xx, 5xx families	Fallback when no exact mapping exists.
503	Eligible 503 responses	Overrides class 5.
404	Eligible 404 responses	Overrides class 4; runtime example remains un-verified.

A class 3 body mapping does not create a redirect or change Location. Each encoded body has a 65,536-character limit including its prefix; see response-body encoding.

Visitor message: Exact 503 or Class 5 in the qualified examples.

Error mapping source

{
  "spec": {
    "more_option": {
      "custom_errors": {
        "3": "string:///PCFkb2N0eXBlIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRhIGNoYXJzZXQ9InV0Zi04Ij48bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoIj48dGl0bGU+Q2xhc3MgMzwvdGl0bGU+PC9oZWFkPjxib2R5PjxtYWluPjxoMT5DbGFzcyAzPC9oMT48cD5GNSBjdXN0b20gcmVzcG9uc2VzIHNob3djYXNlLjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD57e3JlcXVlc3RfaWR9fQ==",
        "4": "string:///PCFkb2N0eXBlIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRhIGNoYXJzZXQ9InV0Zi04Ij48bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoIj48dGl0bGU+Q2xhc3MgNDwvdGl0bGU+PC9oZWFkPjxib2R5PjxtYWluPjxoMT5DbGFzcyA0PC9oMT48cD5GNSBjdXN0b20gcmVzcG9uc2VzIHNob3djYXNlLjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD57e3JlcXVlc3RfaWR9fQ==",
        "5": "string:///PCFkb2N0eXBlIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRhIGNoYXJzZXQ9InV0Zi04Ij48bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoIj48dGl0bGU+Q2xhc3MgNTwvdGl0bGU+PC9oZWFkPjxib2R5PjxtYWluPjxoMT5DbGFzcyA1PC9oMT48cD5GNSBjdXN0b20gcmVzcG9uc2VzIHNob3djYXNlLjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD57e3JlcXVlc3RfaWR9fQ==",
        "404": "string:///PCFkb2N0eXBlIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRhIGNoYXJzZXQ9InV0Zi04Ij48bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoIj48dGl0bGU+RXhhY3QgNDA0PC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkV4YWN0IDQwNDwvaDE+PHA+RjUgY3VzdG9tIHJlc3BvbnNlcyBzaG93Y2FzZS48L3A+PC9tYWluPjwvYm9keT48L2h0bWw+e3tyZXF1ZXN0X2lkfX0=",
        "503": "string:///PCFkb2N0eXBlIGh0bWw+PGh0bWwgbGFuZz0iZW4iPjxoZWFkPjxtZXRhIGNoYXJzZXQ9InV0Zi04Ij48bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoIj48dGl0bGU+RXhhY3QgNTAzPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkV4YWN0IDUwMzwvaDE+PHA+RjUgY3VzdG9tIHJlc3BvbnNlcyBzaG93Y2FzZS48L3A+PC9tYWluPjwvYm9keT48L2h0bWw+e3tyZXF1ZXN0X2lkfX0="
      }
    }
  }
}

Exact 503 decoded preview (escaped):

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Exact 503</title></head><body><main><h1>Exact 503</h1><p>F5 custom responses showcase.</p></main></body></html>{{request_id}}

Class 5 decoded preview (escaped):

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Class 5</title></head><body><main><h1>Class 5</h1><p>F5 custom responses showcase.</p></main></body></html>{{request_id}}

Qualified upstream failures

The two routes below select distinct origin pools. A closed origin port makes the edge generate 503; an origin that exceeds the route timeout makes it generate 504. Put the mappings and routes on the same load balancer, with their referenced pools configured.

Replace each <ORIGIN_POOL_NAME> with its respective fault pool, rather than using one pool for both routes. These fragments show only the qualified failure routes.

{
  "spec": {
    "routes": [
      {
        "simple_route": {
          "path": {
            "path": "/fault/503"
          },
          "origin_pools": [
            {
              "pool": {
                "name": "<ORIGIN_POOL_NAME>",
                "namespace": "<XC_NAMESPACE>"
              },
              "weight": 1,
              "priority": 1
            }
          ],
          "http_method": "ANY"
        }
      },
      {
        "simple_route": {
          "path": {
            "path": "/fault/504"
          },
          "origin_pools": [
            {
              "pool": {
                "name": "<ORIGIN_POOL_NAME>",
                "namespace": "<XC_NAMESPACE>"
              },
              "weight": 1,
              "priority": 1
            }
          ],
          "advanced_options": {
            "timeout": 2000,
            "no_retry_policy": {},
            "priority": "DEFAULT"
          },
          "http_method": "ANY"
        }
      }
    ]
  }
}

These examples passed status, body, healthy-origin control and response-owner checks:

• Exact 503 page returns 503 with “Exact 503”.
• Class 5 timeout page returns 504 with “Class 5”.

Expected result: The exact 503 body takes precedence over class 5; 504 uses the class body. Compare with the healthy / response on this host and confirm which component generated the failure.

Include a per-request identifier

Use the existing {{request_id}} template in a mapped page when you want the visitor’s message to include an identifier for that request. The decoded previews above contain this template. Keep it in the body before encoding the message; the edge substitutes it when rendering these qualified pages.

Measured behavior: Both the exact 503 and class 5 timeout pages exactly matched their accepted templates after substitution. Each repeat request produced a different identifier. The healthy origin response contained no substituted identifier.

1. Open the Exact 503 page linked above and find the identifier in the message.
2. Reload the page to make another request; compare the identifier with the previous response.
3. Open the Class 5 timeout page and repeat the comparison.
4. Navigate to / on the same host and confirm that the healthy application response contains neither this message nor its identifier.

Expected result: The literal {{request_id}} is absent from each error response, and repeated requests have distinct identifiers without changing 503 or 504. This proves template substitution; it does not prove that the identifier appears in a particular log or security event. Do not infer substitution in other response families from these two results.

The sanitized live proof records the template comparisons and controls. Raw runtime identifiers remain outside the public examples.

Eligibility limits

Origin-generated 302, 404, 418, 500 and 503 retained their origin bodies. Parser-generated 400 and 431 retained generic edge bodies. Accepted mapping configuration alone does not establish that a response is eligible.

The path named /fault/502 produced edge 503 with “Exact 503”; its name does not establish a 502. A custom 502, exact 404, and the remaining family mappings remain un-verified examples. Detailed investigation belongs in operator observations.

For deliberately generated 404, 410 and 503 replies, the qualified missing-resource and maintenance routes require matching body mappings. Those results do not imply origin-body replacement.