Диагностика
ответа

§1Посмотреть весь ответ, а не тело

При разборе смотрят на весь ответ, а не только на тело: часть сведений передаётся строкой состояния и заголовками. В терминале их показывает ключ -i:

curl -i http://127.0.0.1:8000/api/v1/tickets/00000000-0000-0000-0000-000000000000

HTTP/1.1 404 Not Found
x-request-id: 3f1c8a77-0a16-4e18-9a3b-9e33c0b7b6a1
content-type: application/problem+json

{
  "type": "https://…/problems/http-404",
  "title": "Resource not found",
  "status": 404,
  "detail": "Ticket 00000000-0000-0000-0000-000000000000 does not exist",
  "instance": "/api/v1/tickets/00000000-0000-0000-0000-000000000000"
}

Те же три части видны в Swagger UI после кнопки Execute, и это удобнее, когда терминала под рукой нет.

§2Первая развилка: чья ошибка

Первая цифра кода отвечает на главный вопрос разбора — где чинить.

От этого различия зависит, кому заводить задачу. При коде 422 в теле ответа уже указано, какое поле не подошло, поэтому обращаться с таким ответом к команде API не нужно.

§3401 и 403: доступ

Оба кода относятся к доступу, но означают разное. По ним клиент решает, что показать пользователю, поэтому различать их обязательно.

curl -i -X POST http://127.0.0.1:8000/api/v1/tickets \
  -H 'Content-Type: application/json' -d '{"title":"Проверка"}'
# -> 401 "Provide a valid Bearer token in the Authorization header"

curl -i -X POST http://127.0.0.1:8000/api/v1/tickets \
  -H 'Authorization: Bearer viewer-token' \
  -H 'Content-Type: application/json' -d '{"title":"Проверка"}'
# -> 403 "This token can only read tickets"

Признак, по которому их различают в чужом API: если после получения нового токена ответ не изменился — это 403 по сути, даже если сервис возвращает 401. Такое встречается, и тогда в свой стандарт записывают правило различать коды явно.

§4404 и 405: адрес и метод

Код 404 сам по себе двусмыслен: по нему не видно, отсутствует адрес или ресурс по этому адресу. Различает эти случаи поле detail.

Код 405 Method Not Allowed однозначен: адрес существует, но этот метод к нему неприменим. По стандарту вместе с ним обязателен заголовок Allow со списком доступных методов — по нему сразу видно, чем заменить.

HTTP/1.1 405 Method Not Allowed
allow: GET
content-type: application/problem+json

Частая причина 405 — попытка отправить PUT туда, где реализован только PATCH, или POST на адрес элемента вместо адреса коллекции. Разницу между этими адресами разбирали в главе 1.3.

§5415 и 422: формат и содержание

Тело запроса проверяется в три этапа, и стандарт разрешает отвечать на них разными кодами: 415 Unsupported Media Type — не тот Content-Type, 400 Bad Request — текст не является JSON, 422 — JSON разобран, но не подходит под схему.

Разрешает, но не обязывает. Учебный сервис на все три случая отвечает 422, а различает их поле errors. Вот три настоящих ответа на три разных запроса:

"errors": [{"loc": ["body"],
             "msg": "Input should be a valid dictionary or object to extract fields from",
             "type": "model_attributes_type"}]

"errors": [{"loc": ["body", "9"], "msg": "JSON decode error", "type": "json_invalid"}]

"errors": [
  {"loc": ["body", "title"], "msg": "String should have at least 3 characters", "type": "string_too_short"},
  {"loc": ["body", "priority"], "msg": "Extra inputs are not permitted", "type": "extra_forbidden"}
]

Читается это так. Первый: прислана форма, а ожидался объект. Второй: разбор JSON споткнулся на девятом символе. Третий: поле title короче трёх символов, и вдобавок прислано поле priority, которого в контракте нет, — почти всегда это опечатка в имени поля или код клиента, написанный под другую версию контракта.

§6429 и 5xx: нагрузка и сбой

Код 429 Too Many Requests означает, что сервис ограничивает частоту запросов. Ответ сообщает, сколько ждать; повторять запрос раньше этого срока бесполезно.

HTTP/1.1 429
retry-after: 60
x-ratelimit-limit: 2
x-ratelimit-remaining: 0
x-ratelimit-reset: 60
content-type: application/problem+json

{
  "type": "https://…/problems/http-429",
  "title": "Too many requests",
  "status": 429,
  "detail": "Write limit of 2 requests per minute exceeded",
  "instance": "/api/v1/tickets"
}

Здесь всё сказано числами: предел — 2 запроса, осталось 0, окно закроется через 60 секунд. Клиент, который читает эти заголовки, ждёт указанное время; клиент, который их не читает, продолжит получать тот же ответ. Заголовки лимитов разбираются в главе 4.3.

С кодами 5xx порядок разбора другой. Тело такой ошибки намеренно не содержит подробностей, поэтому разбор идёт не по ответу, а по журналу сервера.

§7Когда ответа нет вовсе

Отдельный класс случаев: кода состояния нет, потому что ответа не было. Тогда разбор идёт не по HTTP, а по сети.

В последних двух случаях запрос из терминала проходит, а со страницы — нет. Поэтому, разбирая чужую жалобу, уточняйте, откуда отправлялся запрос: из curl или из браузера.

§8Найти запрос в журнале

Каждый ответ учебного сервиса несёт заголовок X-Request-Id. Это ключ, по которому конкретный запрос находится в журнале сервера — среди тысяч похожих.

x-request-id: 8952af24-1c19-4801-8f28-181a89f6265f

grep 8952af24-1c19-4801-8f28-181a89f6265f uvicorn.log

Клиент может прислать свой идентификатор — тогда сервис его сохранит и вернёт обратно. В захваченном ответе учебного сервиса это видно прямо:

HTTP/1.1 200
etag: "4fec2a976840743a"
x-request-id: support-case-1842

Так поступает служба поддержки: в идентификатор ставится номер обращения, и запрос конкретного пользователя находится в журнале по номеру его заявки. Подробности — в главе 4.3.

§9Порядок проверок целиком

1. Повторите запрос с -i. Нужен весь ответ: код, заголовки, тело.
2. Посмотрите на первую цифру кода. 4xx — разбираетесь сами, 5xx — идёте к команде сервиса с X-Request-Id.
3. Прочитайте detail и errors. В большинстве случаев причина написана прямо там.
4. Откройте адрес из поля type. На странице вида проблемы написано, что делать.
5. Сверьтесь с описанием операции в Swagger UI: тот ли метод, тот ли адрес, те ли обязательные поля.
6. Выполните ту же операцию через Swagger UI. Если там получается, дело в вашем запросе, а не в сервисе.
7. Только теперь заводите задачу — с четырьмя строками из §8.