[SIP-40] Proposal for Custom Error Messages

[SIP-40] Proposal for Custom Error Messages

Motivation

The current user experience for error cases in Superset does not provide actionable feedback to users. Error messages often are displayed straight from the backend and are fairly inscrutable. Additionally, there’s no way to customize or add other functionality to these messages on a deployment by deployment basis. A key part of the user experience is providing friendly, actionable messaging when something goes wrong.

Proposed Change

We propose a new, unified pattern for error handling in API endpoints across all of Superset. This will consist of the following work:

1. Unify the backend around a standard error payload for all API errors returned from Superset of the format:

{
  errors: [
    {
      message: string,
      error_type: Enum,
      level: ‘info’ | ‘warning’ | ‘error’,
      extra: Dict[string, Any],
    }, ...
  ]
}

1. Create an Enum on both the server and client side for uniquely identifying error types. The specific type of an error is included in the standard error payload (e.g. ACCESS_DENIED, DB_ENGINE_SYNTAX_ERROR, etc.)
2. Refactor Superset’s frontend to go through a single SupersetAlert component for handling all error messages. This component will import a renderer file that defaults to some generic error customization messages (ex. Adding Request Access links).
3. Allow a Superset admin to specify an override renderer file that gets used instead of the default renderer. This override renderer is injected by leveraging the Registry class from @superset-ui/core to handle the custom renderers registration.

New or Changed Public Interfaces

• All APIs within Superset will return the above error payload on 4xx and 5xx status code responses.
• Client side options will be made public for injecting your own error rendering file

New dependencies

N/A

Migration Plan and Compatibility

No migrations should be necessary, but the new API may not be backwards compatible. Any changes to the current API will be notated in UPDATING.md and should take place prior to v1.0.0.

Rejected Alternatives

Server side rendering of errors was rejected as we’re trying to remove the existing templates and move all rendering to the client side

cc: @kristw @rusackas @nytai @graceguo-supercat @ktmud

[rusackas]

This has been approved/voted. Hooray! Closing 😃

[craig-rueda]

@etr2460, this is great. It looks like a step towards getting all API responses to have a standard shape. One thing that I would change a tiny bit would be the response shape. Enums are awesome for this sort of thing, but one thing I would add would be an error “code” which would simply be an int which can then be taken action upon by the consumer. There’s also the potential for having multiple errors in a given response (think API validation where several keys are required). In my view, Enum names should be used solely for the purpose of code organization, and should not be transmitted to consumers. Instead, error state should depend on the “error code”.

A slight variation to your structure:

{
    "errors": [{
       "code": 123,
       "message": "Something is wrong here",
       "extra": {
           // Additional contextual stuff in here, for instance field validation messages
       }
    }]
}