Ошибки API

Ошибка API: как понять ответ и найти причину

Системная инструкция по клиентским и серверным ошибкам, авторизации, лимитам, таймаутам, JSON и несовместимым изменениям контракта.

Краткий ответ

Ошибка API — это не один конкретный код. Клиент может получить ответ 4xx из-за запроса или доступа, 5xx из-за приложения и инфраструктуры, не дождаться ответа из-за сети и таймаута либо получить статус 200 с неправильным содержимым.

Диагностика начинается с сохранения полного запроса и ответа: метод, URL, параметры, заголовки без секретов, тело, статус, время и идентификатор запроса. Затем нужно определить, воспроизводится ли проблема для других пользователей, данных и экземпляров.

Мониторинг API должен проверять не только доступность адреса. Для критичных методов важны HTTP-статус, время ответа и ожидаемая структура JSON. При этом внешний монитор не заменяет журналы приложения и трассировку запроса.

Как проявляется проблема

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

Клиент получает 400, 401, 403, 404, 409, 422 или 429.
API отвечает 500, 502 или 503.
Соединение не устанавливается, TLS завершается ошибкой или запрос уходит в таймаут.
Статус 200 приходит с пустым, невалидным или неожиданным JSON.
Ошибка возникает только у одного пользователя, роли или ресурса.
После обновления клиента или сервера меняется формат запроса и ответа.

Основные классы ошибок API

Сначала отнесите проблему к классу. Это быстрее, чем проверять весь стек без направления.

Неверный запрос

Метод, параметры, заголовки или тело не соответствуют контракту.

Что обычно видно

400 или 422.
Ошибка конкретного поля.
Рабочий и нерабочий запросы различаются форматом.

Авторизация и права

Клиент не передал действительные данные доступа либо не имеет права на операцию.

Что обычно видно

401 или 403.
Токен истёк или имеет неподходящую область.
Другой пользователь выполняет запрос успешно.

Маршрут и ресурс

Указана неправильная версия, путь, метод или идентификатор.

Что обычно видно

404 или 405.
Запрос отправлен не в то окружение.
Маршрут изменился после обновления.

Конфликт состояния и лимиты

Операция противоречит текущему состоянию либо превышает ограничение.

Что обычно видно

409 или 429.
Повторная операция завершается конфликтом.
В ответе есть сведения о лимите или повторе.

Серверная ошибка

Приложение, прокси или зависимость не обработали запрос корректно.

Что обычно видно

500, 502, 503 или 504.
Проблема совпадает с релизом или нагрузкой.
В серверных журналах есть исключения и таймауты.

Ошибка содержимого при статусе 200

Транспортный уровень успешен, но бизнес-результат или JSON не соответствует ожиданию.

Что обычно видно

Нет обязательного поля.
Возвращается HTML вместо JSON.
Служебное поле содержит ошибочное состояние.

Как диагностировать ошибку API по шагам

Нужен воспроизводимый запрос и точное сравнение с контрактом, а не пересказ сообщения из интерфейса.

Шаг 1

Сохраните запрос и ответ

Запишите метод, URL, параметры, статус, тип содержимого, время и тело. Секреты перед публикацией удалите.

Правильное ли окружение.
Тот ли HTTP-метод.
Есть ли идентификатор запроса.

curl -i -sS https://api.example.ru/v1/resource \
  -H 'Accept: application/json'

# Для JSON-запроса
curl -i -sS -X POST https://api.example.ru/v1/resource \
  -H 'Content-Type: application/json' \
  --data '{"name":"пример"}'

Шаг 2

Определите класс ошибки по статусу

4xx обычно направляет к запросу и доступу, 5xx — к приложению и инфраструктуре. Но окончательный смысл определяется контрактом конкретного API.

Есть ли документированный код ошибки.
Совпадает ли Content-Type с телом.
Не маскирует ли API ошибку статусом 200.

Шаг 3

Сравните с успешным запросом

Сравнение часто быстрее чтения всего кода.

Пользователь и права.
Параметры и тело.
Версия клиента и окружение.

Шаг 4

Сопоставьте с серверными журналами

Для 5xx и необъяснимых 4xx найдите запрос по времени или идентификатору.

Какой обработчик выполнился.
Где возник отказ.
Какие зависимости участвовали.

Шаг 5

Проверьте изменения контракта

После релиза клиент и сервер могут ожидать разные поля, версии и правила.

Удалённые или обязательные поля.
Изменение типа значения.
Несовместимое изменение маршрута или авторизации.

Как читать распространённые коды API

Таблица задаёт направление диагностики, но контракт конкретного API имеет приоритет.

Код	Обычно означает	Что проверить
400	Запрос нельзя корректно разобрать	JSON, параметры, заголовки
401	Нет действительной авторизации	Токен, ключ, срок действия
403	Недостаточно прав	Роль, область доступа, политика
404	Маршрут или ресурс не найден	Версия, путь, идентификатор
409	Конфликт состояния	Повтор операции, текущее состояние
422	Данные понятны, но не проходят проверку	Ошибки полей и бизнес-правила
429	Превышен лимит запросов	Частота, параллельность, повторные попытки
500	Внутренняя ошибка	Логи приложения и зависимости
502	Некорректный ответ upstream	Прокси, процесс, порт, протокол
503	Сервис временно не готов	Готовность, нагрузка, обслуживание

Что делать в зависимости от роли

Действия посетителя, владельца сайта и разработчика различаются. Не стоит начинать с изменений наугад.

Пользователю интеграции

Сначала исключите ошибку собственного запроса.

Сверьте запрос с документацией.
Не публикуйте токены и ключи.
Передайте поддержке время и безопасный пример.

Владельцу API

Ошибки должны быть наблюдаемыми и понятными.

Возвращайте стабильные коды и структуру ошибки.
Добавляйте идентификатор запроса.
Не раскрывайте внутреннюю трассировку клиенту.

Разработчику

Исправление должно учитывать повтор и совместимость.

Найдите первопричину.
Добавьте контрактный тест.
Проверьте поведение клиента при временных отказах.

Как мониторить API без ложного ощущения исправности

Проверка только главной страницы не показывает состояние API, а проверка только статуса не всегда показывает правильность данных.

Проверяйте критичные методы отдельно

Авторизация, профиль, оплата и другие важные endpoint-ы могут ломаться независимо друг от друга.

Передавайте необходимые заголовки

HTTP-монитор UpWatch позволяет задавать заголовки запроса. Для мониторинга используйте отдельные данные доступа с минимальными правами.

Проверяйте JSON

Можно дополнительно проверять ожидаемые поля и значения. Невалидный JSON или несоответствие правилам делает проверку неуспешной.

Разбирайте историю

История показывает статус, длительность, тип ошибки JSON-проверки и восстановление, но не внутреннюю трассировку сервера.

Ограничения внешней проверки

Внешняя проверка не знает бизнес-смысл ответа без настроенных правил.
Не каждый API-метод безопасно запускать регулярно: операции записи могут менять данные.
Для проверки авторизованных методов нужен отдельный технический аккаунт или ключ.
UpWatch не заменяет контрактные, интеграционные и нагрузочные тесты.

Частые вопросы

Ошибка API и недоступность API — одно и то же?

Нет. При ошибке API ответ может прийти, но быть неправильным. При недоступности соединение, TLS или ожидание ответа могут завершиться без HTTP-статуса.

Чем 401 отличается от 403?

401 обычно означает отсутствие или недействительность авторизации. 403 — клиент распознан, но операция ему запрещена.

Чем 400 отличается от 422?

400 часто означает неправильный формат запроса. 422 обычно используют, когда формат понятен, но значения не проходят проверку. Точное значение зависит от документации API.

Может ли API вернуть 200 и при этом ошибиться?

Да. Тело может содержать ошибочное состояние, пустые данные, невалидный JSON или неправильное значение. Поэтому важны проверки содержимого.

Почему API возвращает HTML вместо JSON?

Ответ могла сформировать страница ошибки прокси, веб-сервер, шлюз авторизации или необработанный маршрут.

Какие статусы UpWatch считает неуспешными?

В текущей реализации HTTP-ответы со статусом 400 и выше считаются неуспешными. Дополнительно проверка может завершиться ошибкой из-за транспорта, невалидного JSON или несоответствия JSON-правилу.

Можно ли мониторить POST-запрос?

В проекте предусмотрены настраиваемые HTTP-метод, заголовки и тело запроса. Но для регулярной проверки выбирайте безопасную операцию, которая не создаёт платежи, заказы и другие необратимые изменения.