APIСтандартизация
тема 1 Открыть слайдами →

Часть 8 из 15 · слайды 61–65

Единый формат ошибок

Успешные ответы описаны схемами. Ошибкам нужен такой же единый формат на весь API.

  1. 61Каждый endpoint не должен придумывать свой error JSON
  2. 62RFC 9457 стандартизирует описание ошибок HTTP API
  3. 63Применяем единый error contract
  4. 64Вызываем отсутствующий ресурс
  5. 65Если Problem Details не появляется

61Каждый endpoint не должен придумывать свой error JSON

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

endpoint 1
{"error": "not found"}
endpoint 2
{"message": "User missing"}
endpoint 3
{"status": false}

Три разных JSON приходят одному клиенту. В первом текст ошибки в поле error, во втором — в message, в третьем текста нет вовсе, а status означает не код, а успех.

Нужен единый error contract.

62RFC 9457 стандартизирует описание ошибок HTTP API

RFC 9457 определяет формат Problem Details. Он заменил более старый RFC 7807.

для JSON
Content-Type: application/problem+json
ПолеСмысл
typeURI вида проблемы
titleкраткое описание вида
statusHTTP status code
detailчто произошло в этом запросе
instanceгде именно возникла проблема
rfc-editor.org · RFC 9457СКРИНШОТ · 15.09.2026
RFC 9457, раздел 3: пример ответа 403 Forbidden с Content-Type: application/problem+json. Клик — увеличить.

63Применяем единый error contract

Так учебный проект отвечает на запрос несуществующего обращения.

404 · application/problem+json
{
  "type": "https://example.edu/problems/http-404",
  "title": "Resource not found",
  "status": 404,
  "detail": "Ticket ... does not exist",
  "instance": "/api/v1/tickets/..."
}
ПолеДля чего клиенту
typeветвить обработку: по нему, а не по тексту, программа узнаёт вид ошибки
titleпоказать человеку общий заголовок
statusне читать заголовки, если тело сохранено в лог
detailпоказать подробность конкретного случая
instanceнайти запрос в логах сервера

Клиент знает структуру ошибки независимо от endpoint.

Все обработчики лежат в app/problems.py. Там же ошибки валидации 422 получают дополнительное поле errors со списком неверных полей. Адрес example.edu в версии 1.0.0 никуда не ведёт — как это исправлено, показывает слайд 102.

64Вызываем отсутствующий ресурс

Проверяем контракт ошибок в Swagger UI.

  1. Открыть GET /api/v1/tickets/{ticket_id}.
  2. Нажать Try it out.
  3. Ввести UUID отсутствующего объекта, например 3f2b8c1e-5d4a-4e7b-9c6f-0a1b2c3d4e5f.
  4. Нажать Execute.

Ожидаемый результат:

404
application/problem+json
Swagger UI · ExecuteСКРИНШОТ · 15.09.2026
Request URL, код ответа 404, тело Problem Details с полем type и заголовок content-type: application/problem+json. Клик — увеличить.

65Если Problem Details не появляется

Проверяйте по порядку: каждая следующая проверка имеет смысл, только если предыдущая пройдена.

  1. Правильный ли endpoint указан в запросе.
  2. Действительно ли ресурс отсутствует.
  3. Зарегистрирован ли exception handler: register_problem_handlers(app).
  4. Сохранён ли файл.
  5. Перезапустился ли development server.
  6. Правильный ли HTTP status code вернулся.
  7. Возвращается ли application/problem+json в заголовке.
  8. Обновилась ли OpenAPI schema в /openapi.json.
  1. endpoint
  2. ресурс
  3. handler
  4. файл сохранён
  5. сервер перезапущен
  6. status code
  7. content-type
  8. schema

Кадр крупным планом