Почему HTTP 200 ещё не означает, что API исправен

HTTP 200 OK говорит, что HTTP-запрос успешно обработан на уровне протокола и сервер вернул успешный ответ. Но 200 сам по себе не доказывает, что API выполняет нужную бизнес-функцию.

Endpoint может вернуть 200 и одновременно сообщить в JSON, что база данных недоступна, данные устарели, очередь не работает или операция завершилась внутренней ошибкой. Поэтому надёжная проверка API должна смотреть не только на status code, но и на содержимое ответа, время и бизнес-критерий.

Что на самом деле означает HTTP 200

RFC 9110 определяет 200 как успешное выполнение запроса. Смысл response body зависит от HTTP method: для GET это представление ресурса, для POST — результат или состояние действия и т. д.

HTTP transport
  ↓
200 OK
  ↓
ответ получен успешно

Но над этим уровнем остаётся application semantics:

200 OK
  ↓
JSON valid?
  ↓
нужные поля есть?
  ↓
значения означают успех?
  ↓
критичная зависимость реально работает?

Пример: два одинаковых HTTP 200

Успешный ответ:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok","orders_available":true}

Проблемный ответ:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"error","message":"database unavailable"}

Для проверки только по status code оба ответа одинаковы. Для пользователя — нет.

Почему API вообще возвращает 200 с ошибкой внутри

Причины бывают разные:

• исторический контракт;
• legacy-клиенты;
• GraphQL-подобная модель ответа;
• приложение всегда заворачивает результат в общий envelope;
• разработчик ошибочно использует 200 для всех исходов;
• endpoint является агрегатором и сообщает частичные результаты.

Не нужно автоматически объявлять любой такой контракт неправильным: сначала посмотрите спецификацию конкретного API. Но мониторинг должен учитывать фактическую семантику ответа.

Уровень 1. Проверка соединения

До HTTP нужны:

DNS → TCP → TLS

Если TLS handshake не прошёл, никакого 200 вообще не будет.

Уровень 2. Проверка HTTP status

Для успешного GET ожидаемый критерий может быть:

status == 200

Для другого endpoint нормой может быть 204, 201 или даже контролируемый 4xx в негативном тесте.

Поэтому «любой 2xx» не всегда достаточно точно.

Уровень 3. Проверка Content-Type

Если endpoint обещает JSON:

Content-Type: application/json

а фактически CDN вернул HTML-заглушку с 200, status check это не заметит.

Через curl:

curl -i https://api.example.com/health

Уровень 4. Проверка JSON

curl -sS https://api.example.com/health | jq .

Если jq не может разобрать ответ, API не соответствует ожидаемому JSON-контракту даже при HTTP 200.

Уровень 5. Проверка обязательных полей

Например, контракт требует:

{
  "status": "ok",
  "version": "..."
}

Проверка только валидности JSON недостаточна. Пустой объект {} тоже валидный JSON.

Уровень 6. Проверка значений

Нужно подтвердить конкретный признак:

$.status == "ok"

или другое поле, которое действительно означает работоспособность функции.

Уровень 7. Проверка latency

API может технически возвращать 200, но отвечать настолько медленно, что пользовательский сценарий уже нарушен.

Через curl:

curl -sS -o /dev/null \
  -w 'code=%{http_code} total=%{time_total}s\n' \
  https://api.example.com/health

Один «успешный» запрос за 20 секунд нельзя считать эквивалентом стабильного ответа за нормальное для вашего сервиса время.

Не существует универсального timeout для всех API: порог должен соответствовать реальному SLO и назначению endpoint.

Почему /health тоже может обманывать

Плохой health endpoint:

{"status":"ok"}

который всегда возвращается без проверки критичных зависимостей, подтверждает только то, что процесс способен ответить HTTP.

С другой стороны, health endpoint не должен бездумно проверять все внешние интеграции и превращаться в источник каскадных отказов. Критерий зависит от того, что именно вы хотите доказать.

Проверяйте пользовательскую функцию, а не только технический endpoint

Для интернет-магазина:

/health → 200
/api/catalog → 200
/api/checkout → 200 + {"available": false}

С точки зрения бизнеса сервис уже частично недоступен.

Пошаговая диагностика HTTP 200 с неправильным содержимым

Шаг 1. Сохраните сырой ответ

curl -i https://api.example.com/v1/status

Шаг 2. Проверьте Content-Type

Убедитесь, что пришёл ожидаемый формат.

Шаг 3. Проверьте JSON

curl -sS https://api.example.com/v1/status | jq .

Шаг 4. Проверьте конкретное поле

curl -sS https://api.example.com/v1/status | jq -r '.status'

Шаг 5. Сопоставьте request ID и логи

Если JSON содержит status:error, найдите ту же операцию в application logs.

Шаг 6. Повторите несколько раз

Плавающая проблема может выглядеть так:

A → 200 + status=ok
B → 200 + status=error
C → 200 + status=ok

Это часто указывает на разные backend-инстансы или нестабильную зависимость.

Как выбрать правильный критерий мониторинга

Хороший критерий должен быть:

• стабильным;
• машинно проверяемым;
• связанным с реальной функцией;
• безопасным для частого вызова;
• не зависящим от случайных данных;
• достаточно узким, чтобы объяснять сбой.

Например:

HTTP status = 200
AND response time < выбранного порога
AND JSON $.status = "ok"

Как проверить восстановление

После исправления нужна серия проверок:

HTTP code    → ожидаемый
Content-Type → ожидаемый
JSON parse   → OK
status field → ok
latency      → в допустимом диапазоне
несколько запросов подряд → стабильны

Один 200 после инцидента не доказывает полного восстановления.

Связь с мониторингом

UpWatch можно использовать для проверки API не только по HTTP-коду, но и по JSON-критериям. Это позволяет отличать транспортно успешный 200 от ответа, который не соответствует ожидаемому состоянию приложения.

Для общей методики см. Как мониторить API endpoint и Как проверить доступность REST API.

Типичные ошибки

• считать любой 200 доказательством исправности;
• проверять только валидность JSON;
• выбирать случайное поле без бизнес-смысла;
• игнорировать latency;
• проверять только /health;
• не повторять запрос после инцидента;
• использовать state-changing POST для частого мониторинга без идемпотентности.

Практический чек-лист

1. Определить ожидаемый HTTP code.
2. Проверить Content-Type.
3. Проверить, что JSON разбирается.
4. Проверить обязательные поля.
5. Выбрать одно или несколько значений успеха.
6. Определить допустимое время ответа.
7. Убедиться, что request безопасен.
8. Проверить несколько backend-инстансов серией запросов.
9. Проверить поведение при отказе зависимости.
10. Убедиться, что монитор обнаруживает 200 + error.
11. Проверить recovery серией запросов.
12. Пересматривать критерий при изменении API-контракта.

Источники и спецификации

• RFC 9110: 200 OK
• RFC 9110: HTTP Semantics
• curl: официальная документация
• jq: официальная документация