Introduce app-specific error codes to Gitpod

Context / Motivation

There are many ways that Gitpod can error. In many cases we are showing raw stack traces, very technical errors to users or in some cases (invalid context URL errors) the workspace and IDE can hang completely. These errors often result in quite scary, red and cryptic looking error messages (e.g. stack traces or internal function call information) and often miss an opportunity to provide guidance to our users about what they can do to fix the error. This is particularly prevalent during workspace start / opening a workspace.

This issue proposes introducing application-specific error codes.

What is an app specific error code?

1. A Gitpod defined string such as project_not_found, auth_no_permission
2. Codes are typically quite coarse-grained so we don't have 100's
3. Codes can be namespaced / prefixed according to our needs (here be dragons 🐉 )
4. The code causing the error might change, but the codes do not
5. Codes are centrally defined in a dictionary (in docs)
6. When new behaviour is added to the product, new codes are considered
7. Codes can be mapped to longer descriptions which describe the error, descriptions live centrally
8. Inside the application, all logic is wrapped, and emit only known error codes
9. If a known error cannot be found, an unknown error code is shown and is tracked and logged

Purpose

The purpose of having application specific error codes is:

1. The key of the error code can be referenced in documentation and error reports
2. The occurrences + frequency of the error can be tracked as a product analytics
3. Any undefined error codes or failure states can be tracked (any errors without an app specific error code)
4. The error code can be used in future audit logs for users or organisations when debugging (without trawling logs)
5. Error code descriptions, and suggested actions can live separate to the application code (e.g. in a CMS) where non-technical individuals can experiment with different messages to users, pointing to relevant documentation pages, or providing different user actions.

Scope

1. Define a technical standard for application specific error codes used throughout Gitpod
2. Define a dictionary (preferably in the public documentation that references each error code, what it means and potential mitigation actions or solutions).
3. Implement minimal first few set of error codes, before gradually rolling out to the rest of the application

Example potential error codes / states

1. invalid_context_url (e.g. #11854)

Example implementations, links and "best practices" / standards

• https://stripe.com/docs/error-codes
• https://auth0.com/docs/libraries/common-auth0-library-authentication-errors
• https://jsonapi.org/format/#error-objects

Example 1	Example 2

Example 3	Example 4

Example 5	Example 6

Example 7

Example 8	-

Relates to:

• https://github.com/gitpod-io/gitpod/issues/8933
• https://github.com/gitpod-io/gitpod/issues/9934
• https://github.com/gitpod-io/gitpod/issues/11199
• https://github.com/gitpod-io/gitpod/issues/3738

The issue does not identify files, tests, or entry points to change. Start by defining the application error-code standard and the centrally maintained documentation dictionary, then determine the initial error cases and integration boundaries; done means the standard, dictionary, and minimal first implementation are agreed and documented.