«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",
],
}
Что происходит по шагам:
- Наш
ProblemErrorсразу превращается в problem-ответ. - Всё, что знает DRF, сначала проходит через стандартный обработчик. Так сохраняется полезное поведение:
WWW-Authenticateдля 401,Retry-AfterдляThrottled. Эти заголовки мы копируем в свой ответ. ValidationErrorраскладывается в плоский списокerrors.exc.detailв DRF — вложенная структура из словарей и списков, листья которой — строкиErrorDetailс атрибутом.code(required,invalid,max_length,min_value...). Функция_flattenобходит её и строит JSON Pointer, включая индексы дляmany=Trueи вложенных сериализаторов.- Всё неизвестное — баг. Логируем с полным трейсбеком под случайным
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[]с JSONpointerи собственнымcode. - Неизвестные исключения: лог с
error_id, общий 500, никогдаstr(e). - Один обработчик (DRF
EXCEPTION_HANDLERили middleware) строит все ошибки; view только бросают исключения. - Не забудьте
set_rollback(),handler404/handler500и тесты на формат ошибок.
Итог
Ответ с ошибкой — это интерфейс, а не строка из лога. Статус-код говорит инфраструктуре, что случилось, стабильный code/type говорит клиенту, что делать, а detail объясняет человеку почему. Соберите всё это в одно тело по RFC 9457, стройте его ровно в одном месте, а внутренности оставьте в логах.
// комментарии
Загружаем комментарии...