Все заметки
Программирование

«200 OK», а внутри ошибка: статус-коды, RFC 9457 problem+json и проектирование ошибок API в Django

Клиент не заметил "success": false и показал зелёную галочку. Когда отдавать 400/401/403/404/409/422/429, problem+json, ошибки валидации по полям и один exception handler, который не светит внутренности.

Мобильное приложение вызывает POST /api/orders/42/pay/. Денег в кошельке не хватает. Сервер отвечает 200 OK и телом {"success": false, "error": "Insufficient funds"}. Приложение смотрит на статус, видит 200, рисует зелёную галочку, и пользователь уходит с уверенностью, что заказ оплачен. Через неделю кто-то переводит серверные сообщения на узбекский, строка становится «Mablag' yetarli emas», и ломается даже тот единственный клиент, который всё-таки сравнивал текст (if error == "Insufficient funds").

Ничего экзотического. Так получается, когда ошибки проектируют по остаточному принципу. В этой статье разберём, как проектировать их осознанно: какой статус-код выбрать, как должно выглядеть тело (RFC 9457, application/problem+json), как отдавать ошибки валидации по полям, как не светить внутренности и как всё это подключить в DRF и в обычном Django.

Почему «200 + success: false» ломает всё вокруг

Наивная версия обычно выглядит так:

# views.py — the "everything is 200" anti-pattern
def pay_order(request, order_id):
    try:
        order = Order.objects.get(pk=order_id)
        charge(order)
        return JsonResponse({"success": True})
    except Exception as e:
        # 200 OK, the real reason is buried in free text,
        # and str(e) may contain SQL, table names or card data
        return JsonResponse({"success": False, "error": str(e)})

Проблемы накапливаются:

  • Статус-код врёт. Всё, что стоит между вашим кодом и пользователем, читает строку статуса, а не ваш JSON: HTTP-клиенты (raise_for_status()), политики ретраев, балансировщики, кеши, APM-дашборды с долей 5xx. Если на всё отвечать 200, error rate в мониторинге навсегда равен нулю.
  • Причина записана свободным текстом. Клиент не может надёжно ветвиться по "error": "...": текст меняется, стоит поправить опечатку или добавить перевод.
  • str(e) выдаёт внутренности. В сообщении IntegrityError есть имя constraint и часто само дублирующееся значение; KeyError из SDK платёжки может содержать кусок ответа провайдера; в трейсбеке — пути к файлам. И всё это уходит прямо клиенту.
  • Каждый эндпоинт изобретает свой формат. Один возвращает error, другой message, третий errors: {...}. Во фронтенде появляется отдельный парсер на каждый эндпоинт.

Исправление состоит из трёх частей: правильный статус-код, стандартное тело и одно место в коде, которое формирует и то и другое.

Выбираем статус-код

Статус-код — это грубая категория. Он сообщает универсальному софту, что за сбой произошёл и есть ли смысл повторять запрос. Вот коды, которых хватает в 95% случаев:

Код Смысл Типичный случай Повторять?
400 Bad Request Сломан сам запрос невалидный JSON, неверный тип query-параметра Нет, исправить запрос
401 Unauthorized Не аутентифицирован нет токена, токен истёк или неверен После повторного входа
403 Forbidden Аутентифицирован, но нельзя кассир вызывает админский эндпоинт Нет
404 Not Found Ресурса нет (или вам не положено знать, что он есть) неверный id, чужой заказ Нет
409 Conflict Конфликт с текущим состоянием ресурса заказ уже оплачен, конфликт версий, idempotency key с другим телом Иногда, перечитав состояние
422 Unprocessable Content Синтаксис в порядке, содержимое — нет сумма меньше минимальной, неверный номер телефона Нет, исправить данные
429 Too Many Requests Сработал rate limit слишком много запросов SMS-кода Да, после Retry-After
500 Internal Server Error Наш баг необработанное исключение Возможно, с backoff
502 / 503 / 504 Проблема апстрима или нагрузки платёжный провайдер лежит, техработы, таймаут Да, с backoff и idempotency key

Несколько правил, на которых легко ошибиться:

  • 401 или 403. 401 значит «я не знаю, кто вы». RFC 9110 требует, чтобы ответ 401 содержал заголовок WWW-Authenticate. 403 значит «я знаю, кто вы, и ответ — нет». Повторный логин 403 не исправит.
  • 403 или 404. Если сам факт существования ресурса чувствителен (чужой заказ, карта пользователя), отвечайте 404. Иначе атакующий перебирает id и по 403 понимает, какие из них существуют.
  • 400 или 422. 400 — для запросов, которые сервер не может даже разобрать; 422 — для корректно оформленных запросов, значения которых не прошли валидацию или бизнес-правило. DRF по умолчанию отдаёт на ошибки валидации 400, и многие API делают так же. Это допустимо; важно выбрать одну конвенцию и задокументировать её. Я предпочитаю 422 для валидации: так отделяется «сломан ваш клиент» от «пользователь ввёл что-то не то».
  • 4xx — вина клиента, 5xx — наша. Никогда не отдавайте 500 на ошибку валидации и 400, когда упала база. Доля 5xx — та метрика, из-за которой будят дежурного; пусть она будет честной.

Тело: RFC 9457 problem+json

RFC 9457 (в 2023 году заменил RFC 7807) задаёт стандартный JSON-формат для HTTP-ошибок с media type application/problem+json. В нём пять стандартных полей:

  • type — URI, идентифицирующий тип проблемы. Это основной идентификатор, на который должен опираться клиент. Если поле опущено, подразумевается about:blank, то есть «ничего сверх статус-кода».
  • title — короткое человекочитаемое описание типа проблемы. Оно не должно меняться от случая к случаю (кроме локализации).
  • status — HTTP статус-код, продублированный для удобства.
  • detail — человекочитаемое объяснение именно этого случая.
  • instance — URI конкретного случая (я кладу туда путь запроса).

Всё остальное — extension members, свои поля добавлять можно. В самом RFC 9457 есть пример с массивом errors и полем pointer (JSON Pointer на место в теле запроса) для ошибок валидации. Вот как выглядит ошибка валидации в моих API:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/api/transfers/",
  "code": "validation_error",
  "errors": [
    {"pointer": "#/amount", "code": "min_value", "detail": "Ensure this value is greater than or equal to 1000."},
    {"pointer": "#/recipient/phone", "code": "invalid", "detail": "Enter a valid phone number."}
  ]
}

Каждую ошибку читают двое: программа и человек. type/code — для программы, и они не меняются никогда; title/detail — для человека, их можно переформулировать и переводить когда угодно.

Рядом с type я добавляю короткое поле code. Строго говоря, оно избыточно (последний сегмент URI несёт ту же информацию), но switch (problem.code) приятнее разбора URL, а snake_case-коды совпадают с теми, что уже используют внутри DRF и Django. URI в type не обязан открываться, но это удобное место для документации по каждой ошибке.

Одно место, которое строит все ошибки

Сначала маленький модуль с хелпером и базовым исключением для доменных ошибок. Доменная ошибка — то, о чём знает бизнес-логика и что безопасно показать: «заказ уже оплачен», «недостаточно средств».

# api/problems.py
PROBLEM_BASE = "https://api.example.com/problems/"
PROBLEM_JSON = "application/problem+json"


def problem(status, code, title, detail=None, instance=None, **extra):
    body = {
        "type": PROBLEM_BASE + code.replace("_", "-"),
        "title": title,
        "status": status,
        "detail": detail or title,
        "code": code,
    }
    if instance:
        body["instance"] = instance
    body.update(extra)
    return body


class ProblemError(Exception):
    """Base class for domain errors that are safe to show to the client."""

    status = 400
    code = "bad_request"
    title = "Bad request"

    def __init__(self, detail=None, **extra):
        super().__init__(detail or self.title)
        self.detail = detail
        self.extra = extra

    def to_dict(self, instance=None):
        return problem(self.status, self.code, self.title, self.detail, instance, **self.extra)


class MalformedRequest(ProblemError):
    status = 400
    code = "malformed_request"
    title = "Malformed request body"


class ValidationProblem(ProblemError):
    status = 422
    code = "validation_error"
    title = "Validation failed"


class OrderAlreadyPaid(ProblemError):
    status = 409
    code = "order_already_paid"
    title = "Order is already paid"


class InsufficientFunds(ProblemError):
    status = 422
    code = "insufficient_funds"
    title = "Insufficient funds"

Теперь raise OrderAlreadyPaid(...) из любого места кода несёт свой статус, код и безопасное сообщение. Никаких try/except с вручную собранным JSON в каждой view.

DRF: свой exception handler

DRF позволяет заменить обработчик исключений настройкой EXCEPTION_HANDLER. Стандартный rest_framework.views.exception_handler уже превращает наследников APIException, а также джанговские Http404 и PermissionDenied в ответы, а для всего остального возвращает None (и это становится 500). Мы вызываем его первым и перекраиваем результат:

# api/exceptions.py
import logging
import uuid

from django.conf import settings
from rest_framework import exceptions
from rest_framework.exceptions import ErrorDetail
from rest_framework.response import Response
from rest_framework.settings import api_settings
from rest_framework.views import exception_handler, set_rollback

from .problems import PROBLEM_JSON, ProblemError, problem

logger = logging.getLogger("api")


def _escape(key):
    # JSON Pointer (RFC 6901): "~" -> "~0", "/" -> "~1"
    return str(key).replace("~", "~0").replace("/", "~1")


def _flatten(detail, path=""):
    """Turn DRF's nested error structure into [{pointer, code, detail}, ...]."""
    if isinstance(detail, dict):
        for key, value in detail.items():
            if key == api_settings.NON_FIELD_ERRORS_KEY:
                yield from _flatten(value, path)
            else:
                yield from _flatten(value, f"{path}/{_escape(key)}")
    elif isinstance(detail, list):
        if all(isinstance(item, ErrorDetail) for item in detail):
            for item in detail:
                yield {"pointer": "#" + path, "code": item.code, "detail": str(item)}
        else:  # list of nested objects, e.g. many=True
            for index, value in enumerate(detail):
                yield from _flatten(value, f"{path}/{index}")
    else:
        yield {"pointer": "#" + path, "code": getattr(detail, "code", "invalid"), "detail": str(detail)}


def problem_exception_handler(exc, context):
    request = context["request"]

    if isinstance(exc, ProblemError):
        set_rollback()  # we bypass DRF's handler, so roll back ATOMIC_REQUESTS ourselves
        return Response(exc.to_dict(instance=request.path), status=exc.status,
                        content_type=PROBLEM_JSON)

    response = exception_handler(exc, context)  # handles APIException, Http404, PermissionDenied

    if response is None:
        if settings.DEBUG:
            return None  # keep Django's debug page locally
        error_id = uuid.uuid4().hex
        logger.exception("Unhandled API error %s on %s", error_id, request.path)
        set_rollback()
        body = problem(500, "internal_error", "Internal server error",
                       "Something went wrong on our side. Please try again later.",
                       request.path, error_id=error_id)
        return Response(body, status=500, content_type=PROBLEM_JSON)

    if isinstance(exc, exceptions.ValidationError):
        status = 422
        body = problem(status, "validation_error", "Validation failed",
                       "One or more fields are invalid.", request.path,
                       errors=list(_flatten(exc.detail)))
    else:
        status = response.status_code  # may already be 403 instead of 401, see below
        code = getattr(exc, "default_code", "error")
        if status == 403 and code == "not_authenticated":
            code = "permission_denied"
        detail = exc.detail if isinstance(exc.detail, str) else None
        body = problem(status, code, response.status_text, detail, request.path)

    problem_response = Response(body, status=status, content_type=PROBLEM_JSON)
    for header in ("WWW-Authenticate", "Retry-After"):
        if header in response:
            problem_response[header] = response[header]
    return problem_response
# settings.py
REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": "api.exceptions.problem_exception_handler",
    "DEFAULT_AUTHENTICATION_CLASSES": [
        # The first class decides 401 vs 403 for anonymous requests:
        # TokenAuthentication sends "WWW-Authenticate: Token" -> 401,
        # SessionAuthentication sends nothing -> DRF downgrades to 403.
        "rest_framework.authentication.TokenAuthentication",
        "rest_framework.authentication.SessionAuthentication",
    ],
}

Что происходит по шагам:

  1. Наш ProblemError сразу превращается в problem-ответ.
  2. Всё, что знает DRF, сначала проходит через стандартный обработчик. Так сохраняется полезное поведение: WWW-Authenticate для 401, Retry-After для Throttled. Эти заголовки мы копируем в свой ответ.
  3. ValidationError раскладывается в плоский список errors. exc.detail в DRF — вложенная структура из словарей и списков, листья которой — строки ErrorDetail с атрибутом .code (required, invalid, max_length, min_value...). Функция _flatten обходит её и строит JSON Pointer, включая индексы для many=True и вложенных сериализаторов.
  4. Всё неизвестное — баг. Логируем с полным трейсбеком под случайным error_id и отдаём общий 500 с этим id. Пользователь может назвать его поддержке, вы найдёте его grep'ом в логах, а наружу ничего внутреннего не уходит.

View при этом выглядит как обычный бизнес-код:

# api/views.py
from django.db import transaction
from django.shortcuts import get_object_or_404
from rest_framework.permissions import IsAuthenticated
from rest_framework.response import Response
from rest_framework.views import APIView

from orders.models import Order
from .problems import InsufficientFunds, OrderAlreadyPaid


class PayOrderView(APIView):
    permission_classes = [IsAuthenticated]

    def post(self, request, order_id):
        with transaction.atomic():
            # Someone else's order -> 404, not 403: do not confirm it exists.
            order = get_object_or_404(
                Order.objects.select_for_update(), pk=order_id, customer=request.user
            )
            if order.status == Order.Status.PAID:
                raise OrderAlreadyPaid(f"Order {order.pk} was already paid.", order_id=order.pk)

            wallet = request.user.wallet
            if wallet.balance < order.total:
                raise InsufficientFunds("Your balance is lower than the order total.")

            order.mark_paid(wallet)
        return Response({"id": order.pk, "status": order.status})

Обычный Django: middleware и формы

Без DRF та же идея ложится в middleware. process_exception вызывается, когда view бросает исключение, в том числе Http404 и PermissionDenied, и если он вернул ответ, Django использует именно его:

# api/middleware.py — plain Django, no DRF
import logging
import uuid

from django.core.exceptions import PermissionDenied
from django.http import Http404, JsonResponse

from .problems import PROBLEM_JSON, ProblemError, problem

logger = logging.getLogger("api")


class ProblemJSONMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_exception(self, request, exc):
        if not request.path.startswith("/api/"):
            return None  # HTML pages keep Django's normal error handling

        if isinstance(exc, ProblemError):
            body = exc.to_dict(instance=request.path)
        elif isinstance(exc, Http404):
            body = problem(404, "not_found", "Resource not found", instance=request.path)
        elif isinstance(exc, PermissionDenied):
            body = problem(403, "permission_denied", "Permission denied", instance=request.path)
        else:
            error_id = uuid.uuid4().hex
            logger.exception("Unhandled API error %s on %s", error_id, request.path)
            body = problem(500, "internal_error", "Internal server error",
                           "Something went wrong on our side. Please try again later.",
                           request.path, error_id=error_id)

        return JsonResponse(body, status=body["status"], content_type=PROBLEM_JSON,
                            json_dumps_params={"ensure_ascii": False})
# settings.py
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "api.middleware.ProblemJSONMiddleware",
]

Формы Django уже умеют отдавать машиночитаемые ошибки: form.errors.get_json_data() возвращает {field: [{"message": ..., "code": ...}]}. Остаётся превратить их в pointer'ы:

# api/views.py — plain Django view with a Form
import json

from django.core.exceptions import NON_FIELD_ERRORS
from django.http import JsonResponse
from django.views.decorators.http import require_POST

from transfers.forms import TransferForm
from .problems import MalformedRequest, ValidationProblem


def form_errors(form):
    return [
        {
            "pointer": "#" if field == NON_FIELD_ERRORS else f"#/{field}",
            "code": error["code"] or "invalid",
            "detail": error["message"],
        }
        for field, errors in form.errors.get_json_data().items()
        for error in errors
    ]


@require_POST
def create_transfer(request):
    try:
        payload = json.loads(request.body)
    except (json.JSONDecodeError, UnicodeDecodeError):
        raise MalformedRequest("Request body must be valid JSON.")
    if not isinstance(payload, dict):
        raise MalformedRequest("Request body must be a JSON object.")

    form = TransferForm(payload)
    if not form.is_valid():
        raise ValidationProblem("One or more fields are invalid.", errors=form_errors(form))

    transfer = form.save()
    return JsonResponse({"id": transfer.pk}, status=201)

Грабли, на которые наступают в продакшене

  • DRF отдаёт 403 вместо 401. Для анонимного запроса DRF спрашивает значение WWW-Authenticate у первого класса аутентификации. У SessionAuthentication его нет, поэтому, если он стоит первым, DRF меняет NotAuthenticated на 403. Хотите корректные 401 — ставьте первым класс, который отдаёт заголовок (токен, JWT).
  • Свой обработчик ломает ATOMIC_REQUESTS. DRF ловит исключение внутри view, поэтому транзакция на весь запрос закоммитится. Стандартный обработчик вызывает set_rollback() сам; если ответы собираете вы, вызывайте его тоже, как в коде выше. В обычном Django исключение выходит из atomic-блока раньше, чем его увидит middleware, так что откат уже произошёл.
  • Проглоченные 500 пропадают из error tracking. Когда обработчик возвращает ответ на неизвестное исключение, сигнал got_request_exception не отправляется, и инструменты, подписанные на него, могут промолчать. Либо отправляйте ошибку явно из обработчика, либо используйте интеграцию с логированием, которая ловит logger.exception.
  • Ошибки вне view. Middleware, резолвинг URL и 404 на неизвестный URL при DEBUG=False не проходят ни через process_exception, ни через DRF. Задайте handler404 и handler500 в корневом URLconf, чтобы для путей /api/ они отдавали problem+json (handler404 используется только при DEBUG=False).
  • Content negotiation. Если клиент шлёт только Accept: application/problem+json, стандартный JSONRenderer (application/json) может не подойти. Либо принимайте на клиенте и application/json, либо добавьте наследника рендерера с этим media type.
  • Коды — часть контракта API. Переименовать insufficient_funds — breaking change, как переименовать поле. Сообщения — нет: их можно свободно переписывать и переводить. Переводите title/detail по Accept-Language, но никогда не code.
  • Сообщения валидации, повторяющие ввод. «Карта 8600 1234 5678 9012 заблокирована» — это утечка. Говорите, какое поле неверно, а не что в нём было, особенно для номеров карт, токенов и паролей.
  • Ошибки валидации без кода. raise ValidationError("...") без code= даёт пустой или общий код. В своих валидаторах всегда передавайте code="...", чтобы клиенту было на что опереться.

Тесты не дают контракту поплыть:

# tests/test_problems.py
import pytest
from rest_framework.test import APIClient


@pytest.fixture
def api_client(django_user_model):
    user = django_user_model.objects.create_user("ali", password="s3cret-pass")
    client = APIClient()
    client.force_authenticate(user)
    return client


@pytest.mark.django_db
def test_validation_error_is_problem_json(api_client):
    resp = api_client.post("/api/transfers/", {"amount": "-5"}, format="json")

    assert resp.status_code == 422
    assert resp["Content-Type"].startswith("application/problem+json")
    body = resp.json()
    assert body["code"] == "validation_error"
    assert {"pointer": "#/amount", "code": "min_value"}.items() <= body["errors"][0].items()


@pytest.mark.django_db
def test_anonymous_gets_401_with_challenge():
    resp = APIClient().post("/api/orders/1/pay/")

    assert resp.status_code == 401
    assert "WWW-Authenticate" in resp

А награда на стороне клиента — ветвление становится скучным:

# a client that branches on the code, never on the text
import httpx

resp = httpx.post(url, json=payload, headers=headers, timeout=10)
if resp.is_error and resp.headers.get("content-type", "").startswith("application/problem+json"):
    problem = resp.json()
    match problem.get("code"):
        case "insufficient_funds":
            show_top_up_screen()
        case "order_already_paid":
            show_receipt(problem["order_id"])
        case "validation_error":
            highlight_fields(problem["errors"])
        case _:
            show_generic_error(problem.get("error_id"))

Чеклист

  • 4xx — для проблем клиента, 5xx — только для проблем сервера; никогда 200 с ошибкой внутри.
  • 401 всегда с WWW-Authenticate; чужие ресурсы прячем за 404.
  • 409 для конфликтов состояния, 422 (или 400, но последовательно) для валидации, 429 с Retry-After.
  • Каждое тело ошибки — application/problem+json с type, title, status, detail и стабильным code.
  • Ошибки полей — в errors[] с JSON pointer и собственным code.
  • Неизвестные исключения: лог с error_id, общий 500, никогда str(e).
  • Один обработчик (DRF EXCEPTION_HANDLER или middleware) строит все ошибки; view только бросают исключения.
  • Не забудьте set_rollback(), handler404/handler500 и тесты на формат ошибок.

Итог

Ответ с ошибкой — это интерфейс, а не строка из лога. Статус-код говорит инфраструктуре, что случилось, стабильный code/type говорит клиенту, что делать, а detail объясняет человеку почему. Соберите всё это в одно тело по RFC 9457, стройте его ровно в одном месте, а внутренности оставьте в логах.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯