# Customise the error page

> Change the page visitors see when a web proxy cannot reach its origin, with your own wording, colours and links.

Source: https://www.coritan.com/docs/proxies/web-proxies/custom-error-page/

In the dashboard:

- /dashboard/proxies/web/…/error-page: https://www.coritan.com/dashboard/proxies/web

When the edge cannot reach a web proxy's origin, it answers with its own error page: `502` when the connection fails, and `504` when the origin does not answer within the origin timeout. A web proxy's **Error page** tab puts your own heading, message, logo, links and colours on that page.

Until you turn your own page on, visitors get the Coritan page, or the page of the brand that the web proxy belongs to when that brand has one turned on. The note at the top of the **When the origin is down** card says which.

## Before you begin

- The web proxy is on your [Edge Proxy](https://www.coritan.com/dashboard/proxies/web) list.
- A logo needs an `https://` address. The edge copies the image into the page, so it must be a PNG, JPEG, GIF, WebP or SVG file of 96 KB or less.
- Links need an `https://` address. The support link can also be a `mailto:` address.

## Set up your error page

1. In the dashboard, go to [Edge Proxy](https://www.coritan.com/dashboard/proxies/web), select the web proxy and select the **Error page** tab.
2. Turn on the switch at the top of the **When the origin is down** card. The card then says `Your page`.
3. Enter a **Heading**, up to 80 characters, and a **Message**, up to 500. The message keeps its line breaks. An empty field shows Coritan's words for the failure.
4. Under **How much of the failure the page explains**, choose one:
   - **Everything** shows a diagram of the path from Coritan to your domain to the origin, and a panel with the ray ID, the edge, the time and the failure.
   - **A reference** shows one line with the ray ID and the time, which a visitor can quote to you.
   - **Words only** shows your heading, your message and your links. The ray ID still travels in the `Coritan-Ray` response header.
5. To show your logo, enter its **Logo URL**.
6. To link to a place where visitors can follow the outage, such as a Discord server or a status page, enter the **Updates link** and its **Button label**. The label is `Updates` unless you change it.
7. To link to your support, enter the **Support link**, such as `mailto:alex@example.com`, and its **Button label**. The label is `Contact support` unless you change it.
8. Choose the page's look ([Choose the look](#choose-the-look)).
9. Check the preview beside the form, then select **Save error page**.

While the form holds changes, the caption under it reads `Unsaved changes. The edge picks them up within a few seconds of saving.` **Reset** puts back the saved page.

### Choose the look

**Palette**
: **Light** gives a pale page, a white card and dark text. **Dark** gives a near-black page and card with light text.

**Page background**, **Card**, **Text** and **Accent**
: Colours as `#rrggbb` values, such as `#102a43`, over the palette's own. The accent colours the heading and the support button. An empty field keeps the palette's colour.

**Corners**
: **Sharp corners**, **Soft corners** or **Rounded**.

**Font**
: **Inter (loaded from Google Fonts)** or **The visitor's system font**. The page cannot use a font from your own site, because your site is what is down.

**How the page says 502**
: **Small line above the heading**, **Rounded badge with a status dot**, **Sharp status tag under the message** or **Quietly, in the reference line under the message**. The status code always appears somewhere on the page.

Every page keeps the `Error 502` or `Error 504` label, the `Powered by Coritan` footer and the `Coritan-Ray` header, so visitors and support staff can tell which network answered. While development mode is on, the page shows the full diagnostics whatever you choose here ([Use development mode while you debug](/docs/proxies/web-proxies/settings/#use-development-mode-while-you-debug)).

## Preview the page

The preview shows the page as a visitor would see it, and it follows your changes as you type. Choose **502 · origin down** or **504 · origin too slow** above it to see each page. With the switch off, it shows the page visitors get today.

The preview runs no scripts and uses the dashboard's fonts, so text in Inter looks slightly different on the live page. When it shows **A field is not valid yet**, correct the field that the form marks. **Could not render the preview** means only the preview failed, and saving still works.

## Turn your page off

Turn the switch off and select **Save error page**. Visitors get the Coritan page or the brand's page again, and your words and settings stay saved for the next time you turn the switch on.

## Result

The dashboard confirms `Error page saved. The edge picks it up within a few seconds.`, or `Error page saved.` when the switch is off. The next `502` or `504` for the name shows the page.

## Troubleshooting

`The heading is limited to 80 characters.` or `The message is limited to 500 characters.`
: Shorten the text. The counter under each field shows how many characters it holds.

`The link label is limited to 40 characters.` or `The updates label is limited to 40 characters.`
: Shorten the **Button label** of the support link or of the updates link.

`The logo must be an https:// URL.` or `The updates link must be an https:// URL.`
: Enter an address that starts with `https://`.

`The support link must be an https:// URL or a mailto: address.`
: Enter an `https://` address, or an email address written as `mailto:alex@example.com`.

`The accent colour must be a #rrggbb value.`
: Enter the colour as `#` and six hexadecimal digits, such as `#1d4ed8`. The same message names the background, card or text colour when that field is wrong.

The logo does not appear
: The edge could not copy the image when it published the page: the file is larger than 96 KB, is not a PNG, JPEG, GIF, WebP or SVG image, or did not load within five seconds. The page then links to the image instead, and a logo on the origin that is down cannot load. Host a smaller image somewhere other than the origin. The edge keeps a copied image for up to six hours, so give a new logo a new URL.

Visitors get a different page
: The error page covers `502` and `504` only. A `404` for a name with no web proxy, a `403` from the WAF and a `429` for too many requests keep their own pages ([How web proxies work](/docs/proxies/web-proxies/#how-the-edge-handles-a-request)).

## Related

- [How web proxies work](/docs/proxies/web-proxies/)
- [Change a web proxy's settings](/docs/proxies/web-proxies/settings/)
- [Troubleshoot proxies and join addresses](/docs/proxies/troubleshooting/)

## With the API

The error page is the `error_page` field of `PATCH /api/v1/proxy/routes/{route_id}` ([Change a web proxy's origin](/docs/proxies/web-proxies/change-the-origin/#with-the-api)). Send the whole page each time, because the value replaces the saved page. `{}` removes it.

```bash
curl -X PATCH https://api.coritan.com/api/v1/proxy/routes/31 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "error_page": {
      "enabled": true,
      "heading": "We will be right back",
      "message": "Our site is down for a few minutes while we fix a problem.",
      "detail": "reference",
      "support_url": "mailto:alex@example.com",
      "theme": "dark",
      "accent_color": "#22c55e"
    }
  }'
```

| Field | Values | When left out |
|---|---|---|
| `enabled` | `true` or `false` | `false`, so visitors get the inherited page |
| `heading` | Text, up to 80 characters | Coritan's heading for the failure |
| `message` | Text, up to 500 characters | Coritan's sentence for the failure |
| `detail` | `full`, `reference` or `minimal` | `full` |
| `logo_url` | An `https://` URL | No logo |
| `logo_data` | A base64 `data:` URI of a PNG, JPEG, GIF, WebP or SVG image | Copied from `logo_url` |
| `support_url` | An `https://` URL or a `mailto:` address | No support button |
| `support_label` | Text, up to 40 characters | `Contact support` |
| `updates_url` | An `https://` URL | No updates button |
| `updates_label` | Text, up to 40 characters | `Updates` |
| `theme` | `light` or `dark` | `light` |
| `background_color`, `surface_color`, `text_color`, `accent_color` | `#rrggbb` | The palette's colour |
| `radius` | `sharp`, `soft` or `round` | `soft` |
| `font` | `inter` or `system` | `inter` |
| `status_style` | `plain`, `pill`, `tag` or `inline` | `plain` |

`full`, `reference` and `minimal` are **Everything**, **A reference** and **Words only**. `surface_color` is the card's colour. URLs can be up to 2,048 characters long. Any other value answers `400` with the reason after `error_page: `, such as `error_page: accent_color must be a #rrggbb colour` or `error_page: theme must be one of light, dark`. `GET /api/v1/proxy/routes/{route_id}` returns the saved page as `error_page`, or `null` when there is none.

Render a page without saving it with `POST /api/v1/proxy/routes/{route_id}/error-page/preview`. It takes the `error_page` to render, or `null` for the page visitors get today, and a `status` of `502` or `504`, `502` by default:

```bash
curl -X POST https://api.coritan.com/api/v1/proxy/routes/31/error-page/preview \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"error_page": {"enabled": true, "heading": "We will be right back"}, "status": 504}' \
  -o preview.html
```

The answer is the page's HTML, with a made-up ray ID and failure. A page that does not pass the checks answers `400` with the same messages as the change call.

## API

- `POST /api/v1/proxy/routes/{route_id}/error-page/preview`: Render the page visitors would see, for a block that is not saved yet (https://www.coritan.com/docs/api/reference/client/reverse-proxy/#op-post-api-v1-proxy-routes-route-id-error-page-preview)