Error Handling
Overview
We attempt to handle platform errors gracefully with fallback UIs at appropriate levels of the application. This is achieved by implementing error boundaries which catch errors thrown by their child components.
Error Levels
We have identified a hierarchy of error levels for use within the Platform Framework. Levels typically correlate with a boundary, but it is worth noting that there can be many boundaries handling the same level of error, depending on the component architecture of a particular feature.
Each error level renders a fallback UI appropriate for its severity. For example, Level 1 & 2 errors are fullscreen takeovers because the user experience would be poor if the broken application remains accessible.
At all levels we attempt to show an error code which links to the corresponding external dev docs page, and a trace ID.
Level 1 - Roadblock Error (aka. Host Error)
This is when an issue prevents any of the platform being accessible or usable.
The global navigation bar is not shown, and the user is presented with a simple message with a full page take over, and the option to try logging in again.
Level 2 - Template Error
This is when a page cannot be loaded due to an issue at a template level or other reason. Separate to 404 which relates to a non-existent URL.
The global navigation bar is still available to use to navigate somewhere else within the platform. The user is also presented with a simple message within a full page takeover, and the option to directly contact their tenant admin.
Level 3 - Object Error
This is when an object (or record) cannot be loaded due to an issue with the fetched data or configuration of components.
The global navigation bar is still available to use to navigate somewhere else within the platform. At the level of the issue, the user is presented with our system message component warning of an error.
The message is human-readable, provides a link to contact the users tenant admin directly and also on a second line an error reference code to make bug management more efficient for support.
Level 4 - Group Error
This is when any field within a group of other fields or components (such as a tab) returns an error.
If any field within the tab returns an error none of the fields are shown, and are replaced with the error message.
This is intentionally designed to ensure that multiple error messages do not stack up on a page, confusing the user and breaking layouts.
The global navigation bar is still available to use to navigate somewhere else within the platform. At the level of the issue, the user is presented with our system message component warning of an error.
The message is human-readable, provides a link to contact the users tenant admin directly and also on a second line an error reference code to make bug management more efficient for support.
Level 5 - Component Error
This is when a smaller component returns an error when loading content or attempting to render.
The global navigation bar is still available to use to navigate somewhere else within the platform. At the level of the issue, the user is presented with our system message component warning of an error.
The message is human-readable, provides a link to contact the users tenant admin directly and also on a second line an error reference code to make bug management more efficient for support.