Коды
ответов

§1Зачем нужен код

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

Первая цифра задаёт общее поведение, остальные две уточняют случай. Даже незнакомый код 418 клиент отнесёт к ошибкам запроса, а 503 — к временным неполадкам сервера.

§22xx: запрос выполнен

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

Рядом стоит код 304 Not Modified — формально из класса 3xx, но встречается он в обычной работе с API. Сервер отвечает им на условный запрос, когда представление не изменилось с версии, указанной клиентом:

GET /api/v1/tickets/a8d04cb9-…
If-None-Match: "4fec2a976840743a"

HTTP/1.1 304
etag: "4fec2a976840743a"
# тела нет: клиент использует то, что у него уже есть

Возвращать 200 на каждый успешный запрос — упущенная возможность. Код должен описывать фактический исход: создание, удаление и «ничего не изменилось» выглядят по-разному.

§34xx: исправлять нужно запрос

Коды этого класса сообщают: сервер понял запрос, но выполнить его не может, и повтор без изменений ничего не даст. Ниже — те, что встречаются в учебном сервисе, с настоящими телами ответов.

Разница между 400 и 422 сбивает с толку чаще прочих. 400 — сервер не смог разобрать сообщение: испорченный JSON, неверная кодировка. 422 — сообщение разобрано, но данные не соответствуют схеме: нет обязательного поля, значение вне допустимого диапазона, передано лишнее свойство.

GET /api/v1/tickets?limit=500

HTTP/1.1 422
content-type: application/problem+json

{
  "type": "…/problems/http-422",
  "title": "Validation error",
  "status": 422,
  "detail": "Request does not match the API contract",
  "errors": [{"loc": ["query", "limit"], "msg": "Input should be less than or equal to 100"}]
}

Массив errors — расширение проекта поверх стандартного формата ошибок. Он называет место (query, поле limit) и причину, поэтому клиент может подсветить нужное поле формы, а не показывать общее «ошибка ввода».

§4401 и 403: две разные ситуации

Эти коды путают чаще всех остальных, а разница между ними простая: 401 — сервер не знает, кто перед ним; 403 — знает и отказывает.

POST /api/v1/tickets   # без заголовка Authorization

HTTP/1.1 401
www-authenticate: Bearer
content-type: application/problem+json

{"title": "Authentication required",
 "detail": "Provide a valid Bearer token in the Authorization header"}

DELETE /api/v1/tickets/a8d04cb9-…
Authorization: Bearer viewer-token

HTTP/1.1 403
content-type: application/problem+json

{"title": "Operation forbidden",
 "detail": "This token can only read tickets"}

Разница важна для поведения клиента. Получив 401, приложение отправляет пользователя на вход: возможно, срок токена истёк. Получив 403, оно показывает «недостаточно прав» — повторный вход ничего не изменит.

§55xx: сервер не справился

Коды 5xx означают, что запрос был правильным, а проблема на стороне сервиса. Самый частый — 500 Internal Server Error.

С этим кодом связаны два ограничения. Во-первых, 500 не заменяет коды 4xx: если обращения нет, это 404, а не «внутренняя ошибка». Во-вторых, тело ответа не должно раскрывать устройство системы.

HTTP/1.1 500
content-type: application/problem+json
x-request-id: d7641a75-7d6e-460e-be67-383efdc60d05

{"title": "Internal server error",
 "detail": "Unexpected server error. The incident has been logged."}

В журнале сервера в этот момент записан полный traceback вместе с тем же x-request-id. Если пользователь укажет этот идентификатор в обращении в поддержку, нужная запись находится в журнале поиском по нему.

§6Какой код для какого исхода

В таблице собраны типичные ситуации и коды, которыми на них отвечают.

§7Коды проверяются тестами

Код ответа — часть контракта, а значит, его проверяют автоматически. В учебном проекте для этого есть отдельные тесты: они вызывают операцию и сравнивают код и заголовки с обещанным.

def test_create_without_token_is_401(client):
    response = client.post("/api/v1/tickets", json={"title": "Не работает VPN"})
    assert response.status_code == 401
    assert response.headers["content-type"] == "application/problem+json"
    assert response.headers["WWW-Authenticate"] == "Bearer"

def test_delete_is_204_and_repeat_gives_404(client, writer):
    ticket_id = client.get("/api/v1/tickets").json()["items"][0]["id"]
    first = client.delete(f"/api/v1/tickets/{ticket_id}", headers=writer)
    assert first.status_code == 204
    assert first.content == b""
    assert client.delete(f"/api/v1/tickets/{ticket_id}", headers=writer).status_code == 404

Второй тест заодно фиксирует то, о чём говорилось в главе 2.2: успешное удаление возвращает 204 без тела, а повтор — 404. Если однажды кто-то решит отвечать на удаление кодом 200 с телом, тест упадёт, и изменение не попадёт в основную ветку незамеченным.

...............................                                          [100%]
31 passed in 0.08s