Skip to content

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

example/shop/errors.py
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:

example/shop/services.py
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:

example/shop/errors.py
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:

example/config/settings.py
# 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.

Next

4. The schema and languages