Add types, subtypes, detail messages, and trace IDs for WebAPIError.

Review Request #13263 — Created Sept. 6, 2023 and submitted — Latest diff uploaded

Information

Djblets
release-4.x

Reviewers

WebAPIError historically has taken a numeric error code and message
and used that to convey errors. This requires that callers understand
all error codes (which are pretty opaque) and use error messages to
differentiate between instances of the error. It also encourages
resources to add lots of WebAPIError instances for every possible
problem, or to heavily reuse existing ones (which can lead to a mess of
errors).

This change modernizes this a bit, giving us the following new fields to
include within the err payload:

  • type: A string representation of the error code.
  • subtype: A more specific subtype, used to differentiate between
    instances of an error.
  • detail: A more verbose error message, conveying additional details
    while preserving the primary message.
  • trace_id: A service-specific ID that can help point to one or more
    relevant log entries or user activity, to help diagnose errors.

With this, it's now recommended to create common errors and then
specialize them with a subtype (using with_overrides() on an
as-needed basis or constructing global sub-WebAPIError instances).

All default error instances now provide a type, most namespaced as
{category}-{specific_error}. They're also now documented.

All unit tests pass in Djblets.

Review Board will require an accompanying change for unit tests.

Commits

Files