"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. AnIntegrityErrormessage contains the constraint name and often the duplicated value; aKeyErrorfrom 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, anothermessage, a thirderrors: {...}. 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-Authenticateheader. 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'sabout: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/codeis for the program and must never change;title/detailis 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:
- Our
ProblemErrorgoes straight to a problem response. - Everything DRF knows about goes through the stock handler first. That keeps its useful behavior:
WWW-Authenticatefor 401,Retry-AfterforThrottled. We copy those headers onto our response. ValidationErroris flattened into theerrorslist. DRF'sexc.detailis a nested structure of dicts and lists whose leaves areErrorDetailstrings with a.codeattribute (required,invalid,max_length,min_value...). The_flattenfunction walks it and builds JSON Pointers, including indexes formany=Trueserializers and nested serializers.- Anything unknown is a bug. We log it with full traceback under a random
error_idand 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-Authenticatevalue.SessionAuthenticationhas none, so if it's first, DRF changesNotAuthenticatedto 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 callsset_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_exceptionsignal doesn't fire, and tools hooked into it may stay silent. Either report explicitly from the handler or rely on a logging integration that captureslogger.exception. - Errors outside views. Middleware, URL resolution and
DEBUG=False404s for unknown URLs don't go throughprocess_exceptionor DRF. Sethandler404andhandler500in the root URLconf to return problem+json for/api/paths (note thathandler404is only used whenDEBUG=False). - Content negotiation. If a client sends
Accept: application/problem+jsononly, DRF's defaultJSONRenderer(application/json) may not match. Either acceptapplication/jsontoo on the client or add a renderer subclass with that media type. - Codes are part of the API contract. Renaming
insufficient_fundsis a breaking change, the same as renaming a field. Messages are not: reword and translate them freely. Translatetitle/detailaccording toAccept-Language, nevercode. - 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("...")withoutcode=gives an empty or generic code. Always passcode="..."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+jsonwithtype,title,status,detail, plus a stablecode. - Field errors go into
errors[]with a JSONpointerand a per-fieldcode. - Unknown exceptions: log with an
error_id, return a generic 500, neverstr(e). - One handler (DRF
EXCEPTION_HANDLERor 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...