Can I show a custom error page when the backend returns 404 or 500?

Short answer

Yes, on an HTTP vService. In the Show Content for Backend Service Errors action, the error code (e.g. 404) is selected from the Error Codes list, and the Content Page to be shown and the Status Code are determined; when the Backend Service returns this code, the client sees the custom page instead of the page of the server. Since Status code comes as 200 by default, the actual code is selected; if 404 and 500 are to return with their own codes, a separate action is added for each code. To send the user to another address, Redirect for Backend Service Errors is used; for different content by path, Show Content with the Status Code condition at the On Response stage is used.

Problem: The Error Page of the Server Shows Technical Details

Application servers return their own default pages in case of an error; these pages look different in each application and sometimes contain version information or error details. Without touching the configuration of the Backend Service, the response is replaced with a corporate error page while it passes through TR7.

Solution: Three Methods

All three methods apply only to responses returned from the Backend Service. For the 502/503/504 that TR7 itself produces when the server cannot be reached at all, the Can I show a custom page for 503/502/504 errors generated by TR7 itself? page is consulted.

Your situation	Suitable method
The same custom page for all paths on the selected error codes	Method 1: Show Content for Backend Service Errors
Sending the user to another address on an error code	Method 2: Redirect for Backend Service Errors
A different page by path or by another condition (e.g. JSON for /api/)	Method 3: Show content (On response) + Status code condition

Method 1: Show Content for Backend Service Errors Recommended

• How it works If the code of the response returned from the Backend Service is one of the selected codes, the response is replaced with the selected page and Status code; the action takes no condition.
• Where it is openedLoad Balancer → Actions → Show Content for Backend Service Errors
• Requirement The error page is in Content Pages
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Open the Content Pages form

Load Balancer → Profiles → Content Pages → Add is clicked (how to add).

2

Adım 2 Prepare the page

Content Page Name, Content Type (default text/html) and Content are entered. Since this action does not add a character set to the response, <meta charset="utf-8"> is written in the head section of the page for Turkish characters.

3

Adım 3 Save the page

Add is clicked.

4

Adım 4 Open the action form

Load Balancer → Actions → Add is clicked (how to add).

5

Adım 5 Enter the action name and type

Action Name is entered, and Action Type = Show Content for Backend Service Errors is selected.

6

Adım 6 Define the page for 404

Error Codes = 404, Content Page = the page from step 3, Status Code = 404 (default 200). More than one code can be selected in the Error codes list; however, all of them return with the single Status code value of this action.

7

Adım 7 Save the action

Add is clicked.

8

Adım 8 Add the second action for 500

Steps 4–7 are repeated with Error Codes = 500, Status Code = 500.

9

Adım 9 Edit the vService

On the Load Balancer → Load Balancer vService List screen, the HTTP vService is selected and Edit is clicked.

10

Adım 10 Add the actions to the Actions field

Both actions are selected in the Details → Actions field.

11

Adım 11 Save

Save is clicked. The change is applied without dropping open connections; in a cluster, it is also sent to the peer device with the default auto-sync (with Synchronize if Manual Sync Mode is on). No change is required on the Backend Service side.

Verification

1ResponseClient side

curl -i https://www.example.com/olmayan-sayfa

ExpectedHTTP/1.1 404 + custom page

2LogTR7 side

On the HTTP Logs screen, the request appears with the 404 code.

ExpectedStatus code 404

Method 2: Redirect for Backend Service Errors

• How it works For requests on which one of the selected codes is returned, the client is redirected to another address with 302; the error page of the Backend Service does not go to the client.
• Where it is openedLoad Balancer → Actions → Redirect for Backend Service Errors
• Requirement The page to redirect to (e.g. a search or support page) must exist in a way that does not create a redirection loop
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Open the action form

Load Balancer → Actions → Add is clicked.

2

Adım 2 Select the action type

Action Type = Redirect for Backend Service Errors is selected.

3

Adım 3 Enter the codes and the address

Error Codes = 404; Redirect Location = /arama. The field supports Smart Variable with fx; for example, by adding Path/page of the request [URI] after /arama?kaynak=, the path that was not found is carried to the search page.

4

Adım 4 Save the action

Add is clicked.

5

Adım 5 Edit the vService

The vService is opened with Edit.

6

Adım 6 Add the action to the Actions field

The action is selected in the Details → Actions field.

7

Adım 7 Save

Save is clicked.

Verification

1ResponseClient side

curl -sI https://www.example.com/olmayan-sayfa

Expected302 + Location: /arama…

Method 3: Show Content (On Response) + Status Code Condition

• How it works Show content that works at the response stage, together with the Status code condition and other conditions, returns content only on the desired requests; for example, JSON for requests under /api/ that return 500, and HTML for the others.
• Where it is openedLoad Balancer → Conditions → Status Code · Actions → Show Content
• Requirement The Status code condition can be selected only at the On response stage
• vService type HTTP

Step-by-Step Configuration

1

Adım 1 Prepare the JSON page

With steps 1–3 of Method 1, a page with Content Type = application/json and Content = {"error":"internal_error"} is added (What is the Content Pages profile; how do I prepare my own HTML page?).

2

Adım 2 Open the condition form

Load Balancer → Conditions → Add is clicked (how to add).

3

Adım 3 Define the Status code condition

Criteria = Status Code, Operator = Equals to (default) and the value 500 are entered.

4

Adım 4 Save the condition

Add is clicked.

5

Adım 5 Open the second condition form

The second condition form is opened with Load Balancer → Conditions → Add.

6

Adım 6 Define the path condition

Criteria = Path, the matching Start and the value /api/ are entered.

7

Adım 7 Save the path condition

Add is clicked.

8

Adım 8 Open the action form

Load Balancer → Actions → Add is clicked.

9

Adım 9 Select the action type

Action Type = Show Content is selected.

10

Adım 10 Define the content at the response stage

Execution Level = On response; Content page = the JSON page; Status code = 500; in the Conditions field, the two conditions are selected with and (custom error pages scenario).

11

Adım 11 Save the action

Add is clicked.

12

Adım 12 Edit the vService

The vService is opened with Edit.

13

Adım 13 Add the action to the Actions field

The action is selected in the Details → Actions field.

14

Adım 14 Save

Save is clicked.

Verification

1ResponseClient side

An API path that returns 500 is requested with curl -i https://www.example.com/api/rapor.

ExpectedHTTP/1.1 500 + {"error":"internal_error"}

Common Mistakes

The Status code default is 200

If Status code is not changed, the 404 and 500 responses go to the client with the 200 code; search engines take the error page for content, and monitoring tools do not see the error. The actual error code is selected in each action.

• Expecting the errors that TR7 produces from this action. The 502/503/504 returned when the Backend Service cannot be reached are within the scope not of these actions but of the Show Content for Traffic Manager Errors and Redirect for Traffic Manager Errors actions.
• Combining several codes in a single action and expecting the codes to be preserved. All the codes in a single action return with the same Status code; if the codes are to be preserved, a separate action is added for each code.
• Saving without selecting any code. While Error codes is empty, the action does not change any response.
• Forgetting the Turkish characters. No character set is added to the Show Content for Backend Service Errors response; <meta charset="utf-8"> is written in the page.

How it is done in the documentation

• Show Content for Backend Service Errors · Error Codes
• Show Content for Backend Service Errors · Status Code
• Redirect for Backend Service Errors · Redirect Location
• Show Content · Scenario 4: Custom Error Pages on Backend Service Errors

Related questions

• Can I show a custom page for 503/502/504 errors generated by TR7 itself?
• On an error, is it better to show a page or to redirect?
• What is the Content Pages profile; how do I prepare my own HTML page?