3. Errors¶
EXCEPTION_HANDLER is the library's, so every failure answers in the same
envelope, with success: false and an error_code a client branches on.
Input that is wrong¶
curl -X POST -H 'Content-Type: application/json' -d '{"quantity": 0}' \
http://127.0.0.1:8000/api/orders/
{"success": false, "status_code": 400, "error_code": "validation_error",
"message": "This field is required.",
"data": {"fields": {
"product": [{"code": "required", "message": "This field is required."}],
"quantity": [{"code": "min_value", "message": "Ensure this value is greater than or equal to 1."}]}}}
The first problem in message, for a screen that shows one sentence; every
problem in data.fields, for a form that marks each field - each with a
code, so a client tells "empty" from "too small" without reading
translated text. A nested field is one flat path: items.0.quantity.
The shop's own errors¶
class OutOfStockError(DomainError):
status_code = status.HTTP_409_CONFLICT
default_code = 'out_of_stock'
default_detail = _('There is not enough of this product in stock.')
class StillOrderedError(DomainError):
status_code = status.HTTP_409_CONFLICT
default_code = 'still_ordered'
default_detail = _('This product has orders, and cannot be deleted.')
A service raises them, with what a client can act on in data:
def place_order(product: Product, quantity: int) -> Order:
"""An order, taken from the stock - or OutOfStockError, saying how many there are."""
with transaction.atomic():
locked = Product.objects.select_for_update().get(pk=product.pk)
if locked.stock < quantity:
raise OutOfStockError(data={'available': locked.stock})
Product.objects.filter(pk=locked.pk).update(stock=F('stock') - quantity)
return Order.objects.create(product=locked, quantity=quantity)
curl -X POST -H 'Content-Type: application/json' -d '{"product": 3, "quantity": 1}' \
http://127.0.0.1:8000/api/orders/
{"success": false, "status_code": 409, "message": "There is not enough of this product in stock.",
"data": {"available": 0}, "error_code": "out_of_stock"}
An error written before the library¶
A project's errors from before it - DRF's APIException, no data - answer
in the envelope unchanged:
class PaymentRequiredError(APIException):
status_code = status.HTTP_402_PAYMENT_REQUIRED
default_code = 'payment_required'
default_detail = _('This order is not paid yet.')
{"success": false, "status_code": 402, "message": "This order is not paid yet.",
"data": {}, "error_code": "payment_required"}
A bug¶
Anything nobody designed answers a generic 500. Its text - which can hold a
query, a file path, a person's name - never leaves the server. It is logged
with its traceback and handed to the REPORTER the settings name:
# drf-parcel: the library's own setting. Every key is optional.
DRF_PARCEL = {
'PAGE_SIZE': 10,
'MAX_PAGE_SIZE': 50,
# Two orders at once for the last of a name: a 409, not a 500.
'HANDLE_INTEGRITY_ERRORS': True,
# Where a bug is reported - Sentry, in a real project.
'REPORTER': 'shop.reporting.report',
}
{"success": false, "status_code": 500, "message": "Something went wrong. Please try again.",
"data": {}, "error_code": "internal_error"}
Under DEBUG it is raised instead, so Django's error page shows it.
Every code the library sends is in the reference.