[Документация Yandex Cloud](../../index.md) > [Yandex Smart Web Security](../index.md) > [Концепции](index.md) > Шаблоны ответов

# Шаблоны страниц ответов

Smart Web Security защищает сайты и веб-приложения от информационных угроз, блокируя или пропуская внешние запросы. По умолчанию при блокировке запроса клиенту возвращается стандартная страница Yandex Cloud с определенным кодом ответа и общей информацией. Чтобы настроить страницы ответа под потребности и дизайн вашего сайта, используйте шаблоны ответов.

Шаблоны страниц ответов помогут обеспечить единый формат сообщений, которые Smart Web Security отображает при срабатывании правил профиля безопасности и профиля ARL. Они позволяют безопасно передавать клиенту данные запроса для диагностики, сохранять единый интерфейс вашего веб-приложения и адаптировать страницы под разные платформы.

При взаимодействии с пользователями (запросы из браузера) шаблоны позволяют:

* Сообщить о причине отказа и рекомендуемых действиях.
* Указать требования авторизации и способ получения доступа.
* Информировать о сроках или условиях восстановления доступа.

При обработке API‑запросов шаблоны позволяют:

* Унифицировать ответы при блокировках.
* Возвращать структурированные ответы для удобной обработки клиентом.
* Снизить риск утечки внутренней информации при ответах сервера.
* Упростить диагностику, возвращая данные запроса.
* Управлять поведением клиента через HTTP‑заголовки.
* Сохранять совместимость с интеграциями за счет выбора формата ответа.

При настройке шаблона страницы ответа потребуется указать [код ответа](#answer-code), [формат ответа](#answer-format) и [содержимое ответа](#answer-body). После создания шаблона вы сможете назначить его на все блокирующие действия [профиля безопасности](profiles.md) и [профиля ARL](arl.md), либо на конкретное правило в этом профиле.

## Код ответа {#answer-code}

Можно переопределить стандартную или создать собственную страницу ответа для стандартных [HTTP-кодов](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).

{% cut "Описание кодов ответов" %}

* **Успешные ответы 2xx**
  * 200 OK — запрос успешно выполнен.
  * 201 CREATED — ресурс был создан.
  * 202 ACCEPTED — запрос принят на обработку.
  * 203 NON-AUTHORITATIVE INFORMATION — информация получена не от исходного сервера.
  * 204 NO CONTENT — сервер успешно обработал запрос, но не вернул ответ.
  * 205 RESET CONTENT — сброс просмотра документа после выполнения запроса.
  * 206 PARTIAL CONTENT — сервер возвращает только часть ресурса.
  * 207 MULTI-STATUS — тело сообщения содержит несколько кодов статуса.
  * 208 ALREADY REPORTED — части ресурса уже были перечислены ранее.
  * 226 IM USED — сервер обработал запрос с модификацией содержимого.

* **Перенаправления 3xx**
  * 300 MULTIPLE CHOICES — для ресурса доступно несколько вариантов.
  * 301 MOVED PERMANENTLY — ресурс перемещен навсегда.
  * 302 FOUND — ресурс находится по другому адресу.
  * 303 SEE OTHER — результат по другому URL.
  * 304 NOT MODIFIED — ресурс не изменялся (для кеширования).
  * 305 USE PROXY — доступ к ресурсу должен осуществляться через прокси (устаревший).
  * 307 TEMPORARY REDIRECT — временное перенаправление на другой URL.
  * 308 PERMANENT REDIRECT — ресурс навсегда перемещен на новый URL.

* **Ошибки клиента 4xx**
  * 400 BAD REQUEST — сервер не смог понять запрос.
  * 401 UNAUTHORIZED — требуется аутентификация.
  * 402 PAYMENT REQUIRED — для доступа к ресурсу требуется оплата.
  * 403 FORBIDDEN — доступ запрещен.
  * 404 NOT FOUND — ресурс не найден.
  * 405 METHOD NOT ALLOWED — метод запроса не разрешен.
  * 406 NOT ACCEPTABLE — нет подходящего формата ответа.
  * 407 PROXY AUTHENTICATION REQUIRED — требуется аутентификация на прокси.
  * 408 REQUEST TIMEOUT — время ожидания запроса истекло.
  * 409 CONFLICT — конфликт запроса с текущим состоянием ресурса.
  * 410 GONE — ресурс удален.
  * 411 LENGTH REQUIRED — требуется заголовок Content-Length.
  * 412 PRECONDITION FAILED — условия из запроса не выполнены.
  * 413 PAYLOAD TOO LARGE — слишком большой размер тела запроса.
  * 414 URI TOO LONG — слишком длинный URI запроса.
  * 415 UNSUPPORTED MEDIA TYPE — неподдерживаемый тип медиаданных (Content-Type).
  * 416 RANGE NOT SATISFIABLE — запрошенный диапазон недоступен.
  * 417 EXPECTATION FAILED — ожидание, указанное в запросе, не может быть выполнено.
  * 421 MISDIRECTED REQUEST — запрос направлен на неверный сервер.
  * 422 UNPROCESSABLE ENTITY — запрос корректен, но не может быть обработан сервером.
  * 423 LOCKED — ресурс заблокирован.
  * 424 FAILED DEPENDENCY — запрос не выполнен из-за неудачного предыдущего запроса.
  * 426 UPGRADE REQUIRED — требуется обновление протокола.
  * 428 PRECONDITION REQUIRED — сервер требует запрос с условием (например, If-Match).
  * 429 TOO MANY REQUESTS — слишком много запросов.
  * 431 REQUEST HEADER FIELDS TOO LARGE — слишком большие поля заголовка запроса.

* **Ошибки сервера 5xx**
  * 500 INTERNAL SERVER ERROR — внутренняя ошибка сервера.
  * 501 NOT IMPLEMENTED — сервер не поддерживает необходимую функциональность.
  * 502 BAD GATEWAY — сервер не получил ответ от вышестоящего сервера.
  * 503 SERVICE UNAVAILABLE — сервис временно недоступен.
  * 504 GATEWAY TIMEOUT — сервер не получил вовремя ответ от вышестоящего сервера.
  * 505 HTTP VERSION NOT SUPPORTED — сервер не поддерживает версию HTTP.
  * 506 VARIANT ALSO NEGOTIATES — ошибка согласования содержимого.
  * 507 INSUFFICIENT STORAGE — недостаточно места для хранения ресурса.
  * 508 LOOP DETECTED — обнаружена бесконечная петля при обработке запроса.
  * 510 NOT EXTENDED — необходимы дополнительные расширения для выполнения запроса.
  * 511 NETWORK AUTHENTICATION REQUIRED — требуется сетевая аутентификация.

{% endcut %}

## Формат ответа {#answer-format}

В зависимости от типа клиента можно выбрать формат ответа:

* **HTML** (Content-Type: `text/html`) — страница для браузера, содержит понятное человеку сообщение об ошибке, перенаправлении, получении доступа и так далее.

* **JSON** (Content-Type: `application/json`) — ответ для API-клиентов в структурированном виде, подходит для автоматической обработки и логирования.

* **XML** (Content-Type: `application/xml`) — ответ для систем, где требуется структурированное сообщение в XML‑виде (например, SOAP‑сервисы).

* **Custom** (Content-Type: произвольный) — содержимое ответа в любом другом формате (например, простой текст).

## Содержимое ответа {#answer-body}

_Содержимое ответа_ — обязательное тело ответа в разметке выбранного формата и HTTP-заголовки.

### Тело ответа {#body-response}

_Тело ответа_ — контент страницы, которая будет возвращена клиенту. Объем ответа должен быть не более `2 КБ` (примерно 2000 символов в кодировке UTF-8).

Дополнительно в тело ответа можно добавить динамические данные (пресеты) — идентификатор и время запроса, IP-адрес клиента. Это может быть полезно при отладке приложения или для обращения пользователя в техподдержку.

Содержимое ответа должно соответствовать выбранному формату ответа, например:

* **HTML**

    ```html
    <!doctype html>
    <html lang="ru">
    <head><meta charset="utf-8"><title>403 Forbidden</title></head>
    <body><h1>403 Forbidden</h1><p>Доступ ограничен.</p></body>
    </html>
    ```

* **JSON**

    ```json
    {
    "error": {
        "code": 403,
        "message": "Доступ ограничен.",
        "details": "Недостаточно прав для выполнения операции."
    }
    }
    ```
     
* **XML**
    
    ```xml
    <?xml version="1.0" encoding="UTF-8"?>
    <error>
    <code>403</code>
    <message>Доступ ограничен.</message>
    <details>Недостаточно прав для выполнения операции.</details>
    </error>
    ```

Для добавления дополнительных параметров можно использовать кнопки пресетов в интерфейсе или следующие записи:

* `%unique_key%` — идентификатор запроса;
* `%request_time%` — время запроса;
* `%client_ip%` — IP-адрес клиента.

Пример страницы с дополнительными параметрами:

```html
<html>
<head><title>403 Forbidden</title></head>
<body>
<h1>403 Forbidden</h1>
<p>Доступ ограничен. Если доступ должен быть, передайте в поддержку следующие данные:</p>
<p>Идентификатор: %unique_key%</p>
<p>IP-адрес: %client_ip%</p>
<p>Время запроса: %request_time%</p>
<p>Контакты: security@example.com</p>
</body>
</html>
```

После добавления тела ответа вы можете посмотреть предварительный вид страницы на стороне клиента, нажав кнопку **Предпросмотр**.

### HTTP-заголовки {#http-headers}

Помимо содержимого страницы в ответ можно добавить HTTP-заголовки (не более 10). Это поможет усилить безопасность в браузере, запретить кеширование страниц и управлять поведением клиента. Можно добавить любые стандартные [HTTP-заголовки](https://www.iana.org/assignments/http-fields/http-fields.xhtml), кроме **Content-Type** и **Content-Length**. Задать произвольный **Content-Type** можно в отдельном поле для формата **Custom**.

Примеры HTTP-заголовков:

* `Cache-Control: no-store` (управление кешированием) — не сохранять ответ.
* `Retry-After: 60` (для ответов `429/503`) — информировать клиента, когда можно будет повторить запрос.

## Практические рекомендации {#recommendations}

* Для удобного управления страницами называйте их по коду ошибки. Например, `401-unauthorized-web`, `403-forbidden-ru`, `429-rate-limit-api`.
* Для страниц блокировки и ошибок добавляйте HTTP-заголовок `Cache-Control: no-store`.
* Для страниц блокировки добавляйте в тело ответа контакты (например, электронный адрес поддержки). Чтобы пользователь мог уточнить причину блокировки или сообщить об ошибке.
* Не раскрывайте в теле ответа внутреннюю информацию, например, о правилах и политиках безопасности.
* Без необходимости не подменяйте успешные коды ответа (`2xx`), чтобы не нарушать бизнес‑логику и API‑вызовы.
* Чтобы создать перенаправление (редирект) на другую страницу, создайте шаблон с одним из кодов перенаправления (`301`, `302`, `303`, `304`, `305`, `307`, `308`) и добавьте HTTP-заголовок `Location`.
* Тестируйте страницы ответа, поскольку предпросмотр в интерфейсе Smart Web Security может некорректно отображать кодировки и сложную верстку. При тестировании просматривайте страницу в разных браузерах (Chrome, Firefox, Safari, Edge) и на устройствах с разным разрешением экрана.
* Чтобы избежать проблем с кодировкой, укажите ее в метаданных, например: `<meta charset="UTF-8">`.
* Чтобы не превышать размер тела ответа в `2 КБ`, выносите статический контент (логотипы, изображения, стили CSS) на внешние ресурсы и подгружайте их через ссылки в HTML-разметке. Браузер загрузит этот контент отдельными запросами.

  {% note warning %}

  Чтобы обеспечить доступность внешнего контента, создайте для него исключения в профиле безопасности. Если пользователь заблокирован каким-либо правилом, браузер может не загрузить внешние ресурсы, если они тоже проходят через защиту и попадают под блокировки. В этом случае страница ответа при блокировке отобразится неправильно.

  {% endnote %}

## Добавление шаблона страницы ответа к профилям и правилам {#add-to-profiles-and-rules}

Шаблон профиля отображается при блокировке любым правилом этого профиля. Если для конкретного правила выбран другой шаблон, будет использоваться он. Если профилю или правилам шаблон не назначен, используется шаблон по умолчанию.

[Правила](rules.md), которым можно назначить шаблон страницы:

* Правила профиля безопасности:
  * **Базовое** с действием **Запретить**.
  * **Smart Protection** с действием **Полная защита** или **Защита API**.
  * **Web Application Firewall** с действием **Полная защита** или **Защита API**.
* Правила профиля ARL с действиями **Блокировать запросы свыше лимита** или **Временно блокировать все запросы**.

Дополнительно можно изменить внешний вид окна с проверкой SmartCaptcha. Для этого [создайте новую](../../smartcaptcha/operations/create-captcha.md) или измените уже существующую капчу, привязанную к профилю безопасности.

#### Полезные ссылки {#see-also}

* [Создать шаблон страницы ответа](../operations/template-create.md)
* [Добавить шаблон страницы ответа к профилю или правилу](../operations/template-attach.md)
* [Управлять шаблоном страницы ответа](../operations/template-manage.md)