HTTP-ошибки

Что такое HTTP-ошибки

Любой ответ HTTP начинается с трёхзначного кода состояния. Первая цифра задаёт класс, и по ней сразу понятно, куда смотреть:

Разделение на 4xx и 5xx — главное, что даёт код ответа. 4xx — задача того, кто шлёт запрос: не тот адрес, нет прав, кривые данные. 5xx — задача владельца сервиса, и клиенту остаётся только повторить попытку позже.

Частые коды

Пара 401/403 путается чаще всего: 401 — «я не знаю, кто вы, предъявите ключ или токен», 403 — «я знаю, кто вы, и вам сюда нельзя».

Ошибка 422 подробно

422 Unprocessable Entity (в актуальной спецификации — Unprocessable Content) означает: запрос синтаксически корректен, сервер его разобрал и понял, но принять данные не может — они не проходят проверку по смыслу.

Разница с соседями:

• 400 — сервер не смог разобрать запрос: JSON оборван, кавычка забыта, Content-Type не тот.
• 422 — сервер разобрал, но данные не годятся: email без собаки, qty: -5, обязательное поле пустое, дата окончания раньше даты начала.
• 409 — с данными всё в порядке, но они конфликтуют с текущим состоянием: такой пользователь уже есть.

Строгого требования отвечать именно 422 в стандарте нет — часть API возвращает на валидацию 400. Но большинство современных фреймворков выбрали 422: так делают Laravel, FastAPI, Rails, а также, например, GitHub API. Поэтому при интеграции с чужим сервисом 422 почти всегда читается как «проверь тело запроса».

Ценность кода в том, что тело ответа обычно содержит разбор по полям:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["Поле email должно быть корректным адресом."],
    "qty": ["Поле qty должно быть не меньше 1."]
  }
}

Что делать, если поймали 422: не повторять запрос — без изменений он снова упадёт. Читайте тело ответа: там перечислены конкретные поля. Дальше сверяйтесь со схемой в Swagger / OpenAPI — обычно расходится тип (строка вместо числа), формат даты или пропущено обязательное поле.

Как разбирать ошибки

• Смотрите тело, а не только код. Осмысленный API кладёт в тело причину — код лишь классифицирует её.
• curl -i показывает код и заголовки, curl -v — весь обмен целиком.
• Ошибка в браузере, но не в curl — это почти наверняка CORS, а не ошибка сервера.
• 502 и 504 — это про инфраструктуру. Приложение за прокси упало, не поднялось или не уложилось в таймаут. Смотрите логи Nginx и самого сервиса, а также health check реплик.
• 504 на тяжёлых задачах — норма при неверных таймаутах. Запрос к инференсу на GPU может считаться десятки секунд, а proxy_read_timeout по умолчанию короче. Либо поднимайте таймаут, либо переводите операцию в асинхронную: сразу 202 и очередь.
• Массовые 429 — не поломка, а сигнал: клиент долбит API чаще разрешённого. Ответ обычно содержит Retry-After.
• История запроса целиком восстанавливается по HAR-файлу, если ошибка воспроизвелась у пользователя.

Связанные термины

• HTTP — где живут коды состояния
• API — то, что сообщает об ошибках кодами
• CORS — ошибка в браузере, которой нет на сервере
• HAR-файл — запись запроса с кодом и телом ответа
• Swagger / OpenAPI — где описаны схемы и возможные коды