# Your own error page

When one of your apps can't answer, the visitor gets a page that says so. By default it's Alf's. Give your organization a page of its own and your visitors get that instead: at your apps' smartalfred.com addresses and at your [own domains](/docs/domains).

## Set it

In **Settings → Error page**, write the HTML or choose a file, check the preview, and save. It shows within a few seconds. **Remove** goes back to Alf's pages.

It's one page for the whole organization, and only admins can change it.

## When it's shown

Whenever a request reaches Alf but not your app:

| What happened | Status | `{{code}}` |
| --- | --- | --- |
| The app was asleep and didn't wake in time | 503 | `did_not_wake` |
| Its first version isn't deployed yet | 503 | `not_deployed` |
| It isn't on a server yet | 503 | `not_placed` |
| Its server isn't connected | 503 | `server_offline` |
| It's running but didn't answer | 502 | `no_answer` |

It is **not** shown:

- for errors your app answers with itself (its own 404s and 500s are its business);
- at an address with no app behind it, since there's nobody's page to show;
- while the organization is paused by Alf;
- to programs: anything that doesn't ask for HTML keeps getting the facts as JSON or plain text.

The status code and the headers (`Retry-After`, `X-Smartalfred-Page`) are the same as with Alf's page, so monitoring keeps working.

## Saying what happened

It's one HTML document for every case. These are filled in each time, wherever they appear in it:

| Field | What it holds |
| --- | --- |
| `{{title}}` | What happened, in a few words: "This app is taking too long to wake up" |
| `{{message}}` | A sentence or two for the visitor |
| `{{status}}` | The HTTP status: `503` |
| `{{code}}` | Which case it is, in a word: `did_not_wake` |
| `{{host}}` | The address the visitor asked for |
| `{{retry_after}}` | Seconds until it's worth trying again; empty when waiting won't help |

The values are escaped, so they're safe anywhere in the HTML. Anything else in double braces is left as it is.

A page that uses none of them is fine too: the same words for everything.

## Trying again by itself

Most of these pass within seconds (an app waking, a deploy finishing). Alf's page reloads by itself; yours does if you ask for it:

```html
<meta http-equiv="refresh" content="{{retry_after}}">
```

When there's nothing to wait for the field is empty, and the browser ignores the tag.

## Good to know

- Up to 256 KB. Put styles in the page; link large images rather than inlining them, from somewhere that isn't the app that's down.
- Scripts run on the real page (not in the settings preview).
- The page is served from your app's address, so relative links (`/logo.png`) go to the app that isn't answering. Use full URLs.
- Over the [API](/docs/api): `PUT /api/v1/organizations/{organization_id}/error-page` with `{"html": "…"}`.
- A coding agent can write and set it for you: `set_error_page`, `get_error_page` and `remove_error_page` in the [agent tools](/docs/agent-tools). Not with a token limited to one project, as the page is the whole organization's.