• 
      

    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