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)