Коды ошибок
Справочник причин, которые Upvisor может показать в проверках, инцидентах, публичном API и диагностике.
Как читать ошибки Upvisor
Ошибка в Upvisor обычно состоит из короткой причины и технических деталей проверки. В карточке инцидента причина помогает быстро понять, что произошло, а диагностика показывает контекст: регион проверки, IP, DNS, HTTP-код, TLS, ping, traceroute, mtr и nmap, если они доступны.
Один и тот же сбой может выглядеть по-разному в разных регионах. Например, Москва может получить таймаут, а Алматы — HTTP 502. Поэтому при анализе всегда смотрите регион, время проверки и последние попытки.
Ошибки сети
Эти ошибки появляются, когда агент не может установить или удержать сетевое соединение с целью проверки.
| Ошибка | Технический маркер | Что означает |
|---|---|---|
| Подключение отклонено | ECONNREFUSED | Хост доступен, но сервис на указанном порту не принимает соединение. |
| Соединение сброшено | ECONNRESET, socket hang up | Соединение было разорвано до завершения ответа. Часто связано с proxy, WAF, лимитами или падением upstream. |
| Время ожидания истекло | Request timeout, Connection timeout, ETIMEDOUT | Сервис не ответил за тайм-аут, заданный в мониторе. |
| Сеть недоступна | ENETUNREACH | Маршрут до сети отсутствует или заблокирован на сетевом уровне. |
| Хост недоступен | EHOSTUNREACH | IP найден, но агент не может дойти до хоста. |
| Доступ запрещен | EACCES, EPERM | Операция запрещена правами ОС, firewall или политикой сети. |
| Неверный адрес | EINVAL, Invalid URL, Invalid host | Цель проверки указана в некорректном формате. |
HTTP 4xx
Коды 4xx обычно означают, что сервер понял запрос, но отказался его выполнять или не нашел нужный ресурс. Для мониторинга это ошибка, если код не добавлен в список успешных ответов.
| Код | Название | Что проверить |
|---|---|---|
400 | Bad Request | URL, метод запроса, заголовки и параметры. |
401 | Unauthorized | Нужна авторизация. Для приватных endpoints используйте заголовки в настройках монитора. |
402 | Payment Required | Доступ ограничен оплатой или бизнес-правилом на стороне сервиса. |
403 | Forbidden | WAF, firewall, CDN или приложение блокирует запрос агента. |
404 | Not Found | Путь изменился, страница удалена или редирект ведет не туда. |
405 | Method Not Allowed | Метод HEAD/GET/POST не разрешен для этого endpoint. |
408 | Request Timeout | Сервер закрыл ожидание запроса или слишком долго принимал соединение. |
409 | Conflict | Запрос конфликтует с текущим состоянием ресурса. |
410 | Gone | Ресурс удален окончательно. |
413 | Payload Too Large | Сервер считает тело запроса слишком большим. |
414 | URI Too Long | URL или query string слишком длинные. |
415 | Unsupported Media Type | Неверный Content-Type для проверяемого endpoint. |
418 | I'm a teapot | Нестандартный или тестовый ответ сервера. Добавьте в успешные коды только если это ожидаемо. |
421 | Misdirected Request | Запрос попал не на тот virtual host, часто из-за TLS/SNI или proxy-конфигурации. |
422 | Unprocessable Entity | Endpoint получил данные, но не может их обработать. |
423 | Locked | Ресурс заблокирован. |
425 | Too Early | Сервер не готов принять ранний запрос. |
426 | Upgrade Required | Нужен другой протокол или версия HTTP/TLS. |
429 | Too Many Requests | Сервис ограничивает частоту запросов. Добавьте User-Agent Upvisor в allowlist или увеличьте интервал. |
431 | Header Fields Too Large | Слишком большие заголовки запроса. |
451 | Unavailable For Legal Reasons | Доступ ограничен юридически или географически. |
HTTP 5xx
Коды 5xx почти всегда указывают на проблему на стороне проверяемого сервиса, reverse-proxy, CDN или upstream-приложения.
| Код | Название | Что означает |
|---|---|---|
500 | Internal Server Error | Внутренняя ошибка приложения или backend. |
501 | Not Implemented | Сервер не поддерживает нужный метод или функцию. |
502 | Bad Gateway | Proxy получил некорректный ответ от upstream. Проверьте backend, PHP-FPM, Node.js, upstream socket. |
503 | Service Unavailable | Сервис перегружен, выключен или находится на техработах. |
504 | Gateway Timeout | Proxy не дождался ответа от upstream. |
505 | HTTP Version Not Supported | Сервер не поддерживает версию HTTP. |
506 | Variant Also Negotiates | Ошибка согласования варианта ответа. |
507 | Insufficient Storage | Недостаточно места или ресурсов на сервере. |
508 | Loop Detected | Обнаружен цикл обработки запроса. |
510 | Not Extended | Серверу нужны расширения запроса. |
511 | Network Authentication Required | Сеть требует авторизацию, например captive portal. |
Reverse-proxy, Nginx и CDN
Если перед приложением стоит Nginx, OpenResty, Cloudflare или другой CDN/proxy, ошибка может возникнуть до приложения.
| Ошибка | Как проявляется | Что проверить |
|---|---|---|
| Upstream не отвечает | 502, 504, пустой ответ | Backend-процесс, upstream socket, порт приложения, лимиты worker. |
| HTTP на HTTPS-порту | Разрыв TLS или некорректный HTTP-ответ | Схему URL, редиректы, listen-порты и сертификаты. |
| Слишком большой заголовок | 431, 400 | Размер cookie, proxy buffer, client header buffer. |
| Клиентский сертификат нужен | 400, TLS alert | mTLS-настройки, исключение для User-Agent Upvisor или отдельный endpoint для мониторинга. |
| CDN не видит origin | 521, 522, 523, 524 | Доступность origin-сервера, firewall, DNS origin, allowlist IP/CDN. |
| TLS между CDN и origin сломан | 525, 526 | Сертификат origin, SNI, режим SSL в CDN. |
Ошибки DNS
DNS-ошибки означают, что агент не смог получить ожидаемые записи или запись отличается от настроенного значения.
| Ошибка | Технический маркер | Что сделать |
|---|---|---|
| Хост не найден | ENOTFOUND, DNS returned no addresses | Проверьте домен, NS-записи и наличие A/AAAA/CNAME. |
| Временная ошибка DNS | EAI_AGAIN, SERVFAIL | Повторите позже, проверьте DNS-провайдера и TTL. |
| Запись не найдена | DNS record not found | Убедитесь, что выбран правильный тип записи. |
| Запись не совпадает | DNS record does not match expected value | Проверьте ожидаемый IP/значение в настройках монитора. |
| Адрес заблокирован как непубличный | Blocked private/service address | Upvisor не проверяет private, loopback, link-local и metadata-адреса из внешних агентов. |
Ошибки SSL/TLS
SSL/TLS-ошибки появляются при проверке сертификата, TLS-рукопожатия или срока действия сертификата.
| Ошибка | Маркер | Что означает |
|---|---|---|
| Сертификат истек | Certificate invalid or expired | Срок действия сертификата закончился или сертификат не удалось прочитать. |
| Сертификат скоро истекает | Статус деградации SSL | До окончания осталось меньше порога уведомления. |
| Имя хоста не совпадает | ERR_TLS_CERT_ALTNAME_INVALID | Домен отсутствует в SAN/CN сертификата. |
| Самоподписанный сертификат | DEPTH_ZERO_SELF_SIGNED_CERT | Сертификат не выпущен доверенным центром сертификации. |
| Недоверенная цепочка | UNABLE_TO_VERIFY_LEAF_SIGNATURE, SELF_SIGNED_CERT_IN_CHAIN | Не хватает промежуточного сертификата или цепочка собрана неверно. |
| TLS-таймаут | TLS timeout | Сервер не завершил TLS-рукопожатие за отведенное время. |
| Слишком слабые параметры | DH_KEY_TOO_SMALL | Сервер использует устаревшие параметры шифрования. |
Ping и TCP
| Ошибка | Маркер | Описание |
|---|---|---|
| ICMP заблокирован | Хост не ответил на ICMP-запрос | Сервер или firewall может блокировать ping, хотя HTTP/TCP работает. |
| ICMP недоступен на узле | SOCK_RAW, cap_net_raw | На проверочном узле нет прав на raw socket. Такие детали скрываются в публичных инструментах. |
| Потери пакетов | % packet loss | Часть ICMP-пакетов не вернулась. При больших потерях проверка считается ошибочной. |
| TCP-порт закрыт | ECONNREFUSED | Хост отвечает, но сервис на порту не слушает. |
| TCP-таймаут | Connection timeout | Соединение с портом не установлено за тайм-аут. |
Ключевые слова и Heartbeat
| Ошибка | Маркер | Что означает |
|---|---|---|
| Ожидаемый текст не найден | Expected text was not found | Страница загрузилась, но нужной строки в ответе нет. |
| Запрещенный текст найден | Forbidden text was found | В режиме «успех, если текста нет» Upvisor обнаружил запрещенную строку. |
| Heartbeat не пришел | Heartbeat не поступал | Cron-задача или воркер не отправили сигнал вовремя. |
| Heartbeat сообщил ошибку | Heartbeat reported failure | Ваша задача сама вызвала fail-endpoint. |
| Heartbeat token не найден | heartbeat_not_found | URL heartbeat некорректный или монитор удален. |
Ошибки API
REST API возвращает короткий код в поле error. Для пользовательских действий в интерфейсе Upvisor показывает понятный текст, а внутренний код ошибки сохраняет в журнал.
| Код | Описание | Что сделать |
|---|---|---|
missing_api_key | Не передан Bearer-токен. | Добавьте заголовок Authorization: Bearer upv_api_xxx. |
invalid_api_key | Ключ не найден или удален. | Создайте новый ключ в разделе API и MCP. |
insufficient_scope | Ключ не имеет нужного права. | Для POST/PATCH нужен ключ с правом записи. |
feature_not_available | Функция недоступна на текущем тарифе. | Проверьте тариф проекта. |
not_found | Объект не найден или не принадлежит проекту. | Проверьте ID и проект API-ключа. |
rate_limited | Слишком много запросов. | Снизьте частоту запросов и повторите позже. |
invalid_monitor_type | Тип монитора не поддерживается тарифом или API. | Используйте доступный тип проверки. |
monitor_limit_exceeded | Лимит мониторов исчерпан. | Удалите лишний монитор или увеличьте тариф. |
invalid_maintenance_period | Окно техработ задано неверно. | Убедитесь, что окончание позже начала. |
Что отправить в поддержку
- ID монитора или инцидента.
Так быстрее найти проверку в журнале. - Регион проверки.
Ошибка может быть локальной для конкретной сети или страны. - Время ошибки.
Укажите часовой пояс, если копируете время из внешней системы. - Текст причины.
Например:Unexpected HTTP status 502,Connection timeoutилиDNS record does not match expected value.
Связанный раздел
Посмотрите, как Upvisor снижает риск ложных тревог.
Ложные срабатывания
Посмотрите, как Upvisor снижает риск ложных тревог.