Problem
Details

§1Что не так с самодельными ошибками

В сервисе, где формат ошибки не задан, он складывается сам — и по-разному в каждом обработчике. Через год в одном API живут все четыре варианта сразу:

{"error": "not found"}
{"message": "Ticket 42 does not exist", "code": 1204}
{"ok": false, "errors": ["ticket_not_found"]}
Ticket not found          # просто текст, без JSON

Клиенту приходится писать разбор под каждую операцию, а при добавлении новой — выяснять опытным путём, какой из вариантов ему достался. Стандарт снимает эти вопросы: формат один и описан заранее.

§2Стандарт: RFC 9457

Problem Details for HTTP APIs — документ RFC 9457, статус Standards Track. Он описывает формат тела ответа для случая, когда что-то пошло не так, и набор полей этого тела.

Обратите внимание на ключевое слово SHOULD. Оно означает требование, от которого можно отступить, но отступление нужно обосновать. Уровни MUST, SHOULD и MAY разобраны в главе 6.1; здесь достаточно того, что несуществующий адрес в поле type стандарту не соответствует.

§3Пять полей

Вот настоящий ответ учебного сервиса на изменение обращения с устаревшей версией:

{
  "type": "https://maximbytecamp.github.io/api-standard-template/problems/http-412",
  "title": "Precondition failed",
  "status": 412,
  "detail": "Ticket was changed after the version in If-Match was read",
  "instance": "/api/v1/tickets/a8d04cb9-87ea-49b9-8ef6-ba10bbbad82b"
}

§4Media type application/problem+json

Тело ошибки отдаётся не с обычным application/json, а с особым типом application/problem+json. Смысл в том, что клиент понимает формат ещё до разбора тела: суффикс +json говорит «это JSON», а основа problem — «это ошибка по RFC 9457».

В учебном проекте это правило доведено до конца: все ответы 4xx и 5xx используют этот media type, и за этим следит тест из главы 3.3. Того же требует свод правил Zalando.

§5Свои поля: ошибки проверки

Пяти полей хватает не всегда. Когда клиент прислал тело, не подходящее под схему, ему нужно знать не только «проверка не прошла», но и какое поле виновато. Стандарт это предусматривает: к пяти полям разрешено добавлять свои.

{
  "type": "…/problems/http-422",
  "title": "Validation error",
  "status": 422,
  "detail": "Request does not match the API contract",
  "instance": "/api/v1/tickets",
  "errors": [
    {"loc": ["body", "title"], "msg": "String should have at least 3 characters", "type": "string_too_short"}
  ]
}

Поле errors — собственное расширение проекта, и в этом нет нарушения: базовые пять полей на месте, клиент, который о расширении не знает, просто его не заметит. Внутри каждой записи — путь до поля (loc), человеческое пояснение (msg) и машинный код вида ошибки (type). Формы в интерфейсе подсвечивают проблемное поле именно по loc.

§6Страница вида проблемы

Вернёмся к требованию из §2: по адресу в поле type должна открываться документация. В учебном проекте такие страницы собираются из описания и публикуются на GitHub Pages — по одной на каждый вид проблемы.

Такая страница отвечает на три вопроса: когда эта ошибка возникает, что она значит и что делать клиенту. Третий пункт важнее первых двух: для 412 ответ «перечитайте ресурс, возьмите новый ETag и повторите запрос», и это готовая инструкция, а не описание симптома.

§7Как это устроено в коде

Формат задаётся в одном месте — модуль app/problems.py. Ни один обработчик операций не собирает тело ошибки сам.

PROBLEM_MEDIA_TYPE = "application/problem+json"
PROBLEM_TYPE_BASE = os.getenv("API_PROBLEM_TYPE_BASE", "https://…/problems/")

TITLES = {400: "Bad request", 401: "Authentication required", 403: "Operation forbidden",
          404: "Resource not found", 412: "Precondition failed", 422: "Validation error",
          429: "Too many requests", 500: "Internal server error", …}

def problem(status, detail, instance, headers=None, **extra) -> JSONResponse:
    body = {"type": f"{PROBLEM_TYPE_BASE}http-{status}", "title": TITLES[status], "status": status}
    if detail:
        body["detail"] = detail
    body["instance"] = instance
    body.update(extra)
    return JSONResponse(body, status_code=status, headers=headers, media_type=PROBLEM_MEDIA_TYPE)

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

Третий обработчик нужен для того, чтобы контракт соблюдался и при непредвиденной ошибке: без него необработанное исключение вернуло бы страницу с трассировкой и другим media type, то есть ответ, не соответствующий описанию.

§8Чего в ошибке быть не должно

Ошибка уходит наружу, и её содержимое видит кто угодно, включая того, кто ищет слабое место. Поэтому у обработчика 500 формулировка нарочно общая:

async def unhandled_exception_handler(request, exc) -> JSONResponse:
    # Traceback остаётся в логах сервера, клиент получает только публичное описание.
    request_id = getattr(request.state, "request_id", "-")
    logger.exception("Unhandled error on %s %s, request id %s", request.method, request.url.path, request_id)
    return problem(500, "Unexpected server error. The incident has been logged.", request.url.path)

Для такого разделения и нужен заголовок X-Request-Id: он остаётся у клиента и одновременно записан в журнале сервера. Подробно о нём — в главе 4.3.

§9Как делают другие

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