• 
      

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

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

    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.

    Summary ID
    Add types, subtypes, detail messages, and trace IDs for WebAPIError.
    `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.
    203e4ffdbb176d688875ee241691a4eb998a18cc
    david
    1. Ship It!
    2. 
        
    chipx86
    Review request changed
    Status:
    Completed
    Change Summary:
    Pushed to release-4.x (4168c53)