All notes
Programming

"200 OK" with an error inside: status codes, RFC 9457 problem+json and API error design in Django

The client never saw "success": false and showed a green checkmark. When to use 400/401/403/404/409/422/429, problem+json, field-level validation errors, and one exception handler that never leaks internals.

A mobile app calls POST /api/orders/42/pay/. The user has too little money in the wallet. The server answers 200 OK with {"success": false, "error": "Insufficient funds"}. The app checks the status code, sees 200, shows a green checkmark, and the user leaves thinking the order is paid. A week later someone translates the server messages into Uzbek, the string becomes "Mablag' yetarli emas", and the one client that did look at the text (if error == "Insufficient funds") stops working too.

Nothing here is exotic. It is what happens when errors are designed as an afterthought. In this post I want to show how to design them on purpose: which status code to pick, what the body should look like (RFC 9457, application/problem+json), how to return field-level validation errors, how not to leak internals, and how to wire all of it into DRF and into plain Django.

Why "200 + success: false" breaks things

The naive version usually looks like this:

# 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)})

The problems pile up:

  • The status code lies. Everything that sits between your code and the user reads the status line, not your JSON: HTTP client libraries (raise_for_status()), retry policies, load balancers, caches, APM dashboards that count 5xx rate. With 200 for everything, your error rate in monitoring is always zero.
  • The reason is free text. A client can't branch on "error": "..." reliably: the text changes when you fix a typo or add a translation.
  • str(e) leaks internals. An IntegrityError message contains the constraint name and often the duplicated value; a KeyError from a payment SDK may contain part of the response; a traceback contains file paths. All of it goes straight to the client.
  • Every endpoint invents its own shape. One returns error, another message, a third errors: {...}. The frontend ends up with a parser per endpoint.

The fix has three parts: the right status code, a standard body, and one place in the code that produces both.

Choosing the status code

The status code is the coarse category. It tells generic software what kind of failure this is and whether retrying makes sense. Here are the ones you need 95% of the time:

Code Meaning Typical case Retry?
400 Bad Request The request itself is broken invalid JSON, wrong type of query parameter No, fix the request
401 Unauthorized Not authenticated no token, expired or invalid token After re-login
403 Forbidden Authenticated, but not allowed a cashier calls an admin endpoint No
404 Not Found No such resource (or you may not know it exists) wrong id, someone else's order No
409 Conflict Conflicts with the current state of the resource order already paid, version mismatch, idempotency key reused with a different body Sometimes, after re-reading state
422 Unprocessable Content Syntax is fine, content is not amount below minimum, invalid phone number No, fix the data
429 Too Many Requests Rate limit hit too many SMS code requests Yes, after Retry-After
500 Internal Server Error Our bug unhandled exception Maybe, with backoff
502 / 503 / 504 Upstream or capacity problem payment provider down, maintenance, timeout Yes, with backoff and an idempotency key

A few rules that are easy to get wrong:

  • 401 vs 403. 401 means "I don't know who you are". RFC 9110 requires a 401 response to carry a WWW-Authenticate header. 403 means "I know who you are, and the answer is no". Logging in again won't change a 403.
  • 403 vs 404. If the mere existence of a resource is sensitive (someone else's order, a user's card), answer 404. Otherwise an attacker can enumerate ids and learn which ones exist from the 403s.
  • 400 vs 422. 400 is for requests the server can't even parse; 422 is for well-formed requests whose values fail validation or a business rule. DRF returns 400 for validation errors by default and many APIs do the same. That's acceptable; what matters is picking one convention and documenting it. I prefer 422 for validation because it separates "your client is broken" from "your user typed something wrong".
  • 4xx is the client's fault, 5xx is ours. Never return 500 for a validation problem and never return 400 when your database is down. The 5xx rate is the metric that wakes people at night; keep it honest.

The body: RFC 9457 problem+json

RFC 9457 (which replaced RFC 7807 in 2023) defines a standard JSON shape for HTTP errors with the media type application/problem+json. It has five standard members:

  • type — a URI that identifies the problem type. It's the primary identifier clients should rely on. If omitted, it's about:blank, meaning "nothing more than the status code".
  • title — a short human-readable summary of the problem type. It shouldn't change from occurrence to occurrence (except for localization).
  • status — the HTTP status code, duplicated for convenience.
  • detail — a human-readable explanation of this specific occurrence.
  • instance — a URI identifying this occurrence (I use the request path).

Anything else is an extension member, and you're free to add your own. RFC 9457 itself shows an errors array with pointer (a JSON Pointer into the request body) for validation problems. Here's what a validation error looks like in my APIs:

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."}
  ]
}

Two audiences read every error: a program and a person. type/code is for the program and must never change; title/detail is for the person and may be reworded or translated any time.

I add a short code extension next to type. Strictly speaking it's redundant (the last segment of the URI carries the same information), but switch (problem.code) is more pleasant than parsing URLs, and the snake_case code matches what DRF and Django already use internally. The type URI doesn't have to resolve, but it's a nice place to put documentation for each error.

One place that builds every error

First, a tiny module with a helper and a base exception for domain errors. A domain error is something the business logic knows about and is safe to show: "order already paid", "insufficient funds".

# 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"

Raising OrderAlreadyPaid(...) from anywhere in the code now carries its status, its code and its safe message. There's no try/except with a hand-built JSON in every view.

DRF: a custom exception handler

DRF lets you replace its exception handler with the EXCEPTION_HANDLER setting. The default handler, rest_framework.views.exception_handler, already converts APIException subclasses, Django's Http404 and PermissionDenied into responses, and returns None for everything else (which then becomes a 500). We call it first and reshape its output:

# 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",
    ],
}

What happens step by step:

  1. Our ProblemError goes straight to a problem response.
  2. Everything DRF knows about goes through the stock handler first. That keeps its useful behavior: WWW-Authenticate for 401, Retry-After for Throttled. We copy those headers onto our response.
  3. ValidationError is flattened into the errors list. DRF's exc.detail is a nested structure of dicts and lists whose leaves are ErrorDetail strings with a .code attribute (required, invalid, max_length, min_value...). The _flatten function walks it and builds JSON Pointers, including indexes for many=True serializers and nested serializers.
  4. Anything unknown is a bug. We log it with full traceback under a random error_id and return a generic 500 with that id. The user can quote it to support, you can grep it in the logs, and nothing internal leaves the server.

A view then looks like ordinary business code:

# 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})

Plain Django: middleware and forms

Without DRF the same idea fits into a middleware. process_exception is called when a view raises, including Http404 and PermissionDenied, and if it returns a response Django uses that response:

# 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 forms already produce machine-readable errors: form.errors.get_json_data() returns {field: [{"message": ..., "code": ...}]}. We just map it to pointers:

# 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)

Pitfalls I see in production

  • DRF returns 403 instead of 401. For an anonymous request DRF asks the first authentication class for a WWW-Authenticate value. SessionAuthentication has none, so if it's first, DRF changes NotAuthenticated to 403. Put a class that provides the header (token, JWT) first if you want correct 401s.
  • A custom handler breaks ATOMIC_REQUESTS. DRF catches the exception inside the view, so the request-wide transaction would commit. The stock handler calls set_rollback() for you; if you build responses yourself, call it too, as in the code above. In plain Django the exception leaves the atomic block before middleware sees it, so the rollback already happened.
  • Swallowed 500s disappear from error tracking. When the handler returns a response for an unknown exception, Django's got_request_exception signal doesn't fire, and tools hooked into it may stay silent. Either report explicitly from the handler or rely on a logging integration that captures logger.exception.
  • Errors outside views. Middleware, URL resolution and DEBUG=False 404s for unknown URLs don't go through process_exception or DRF. Set handler404 and handler500 in the root URLconf to return problem+json for /api/ paths (note that handler404 is only used when DEBUG=False).
  • Content negotiation. If a client sends Accept: application/problem+json only, DRF's default JSONRenderer (application/json) may not match. Either accept application/json too on the client or add a renderer subclass with that media type.
  • Codes are part of the API contract. Renaming insufficient_funds is a breaking change, the same as renaming a field. Messages are not: reword and translate them freely. Translate title/detail according to Accept-Language, never code.
  • Validation messages that echo input. "Card 8600 1234 5678 9012 is blocked" is a leak. Say which field is wrong, not what was in it, especially for card numbers, tokens and passwords.
  • Validation errors without a code. raise ValidationError("...") without code= gives an empty or generic code. Always pass code="..." in custom validators so clients have something stable to branch on.

Tests keep the contract from drifting:

# 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

And the reward on the client side is that branching becomes boring:

# 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"))

Checklist

  • 4xx for client problems, 5xx only for server problems; never 200 with an error inside.
  • 401 always carries WWW-Authenticate; hide others' resources behind 404.
  • 409 for state conflicts, 422 (or 400, consistently) for validation, 429 with Retry-After.
  • Every error body is application/problem+json with type, title, status, detail, plus a stable code.
  • Field errors go into errors[] with a JSON pointer and a per-field code.
  • Unknown exceptions: log with an error_id, return a generic 500, never str(e).
  • One handler (DRF EXCEPTION_HANDLER or a middleware) builds every error; views only raise.
  • Remember set_rollback(), handler404/handler500, and tests for the error format.

Takeaway

An error response is an interface, not a log message. The status code tells generic infrastructure what happened, the stable code/type tells your client what to do, and detail tells the human why. Put all three in one RFC 9457 body, build it in exactly one place, and keep the internals in your logs.

// comments

Loading comments...

    // next step

    Let's build something together.

    Message me on Telegram
    aslbek@asldev: ~
    ❯