Error Handling in Data SDK (Beta)

GraphQL can return both data and errors in the same response for partial success. Follow these error-handling strategies:

This strategy ensures a complete failure if any GraphQL errors are present in the response, regardless of whether partial data was also returned. It is the most conservative approach, guaranteeing that the application only processes data when the request was entirely successful. Use this strategy with queries where incomplete data would be misleading.

This strategy is suitable for cases where partial data is still usable by the application, even if errors were encountered during the GraphQL request. The errors are logged for review, but the application continues to process the available data. Use this strategy when partial data is still useful and the UI can degrade gracefully, such as with an error on an optional field.

This is the least restrictive strategy. It permits the application to use any data that was successfully retrieved, even if partial errors occurred during the GraphQL request. The application only throws an error and fails if the response contains errors and no usable data was returned. For example, you can use this strategy in mutations where the operations succeed but some return fields aren't accessible.

When handling fetch() errors for the Data SDK, consider transport and runtime errors where no responses are returned. For example, transport errors can include network failures, aborted requests, or runtime exceptions.

Wrap transport errors and check the response.

When handling fetch() errors for the Data SDK, you can run into HTTP app errors with a non-2XX response that includes an error payload. For auth-sensitive flows, consider handling 401 and 403 errors with dedicated user actions, such as a sign-in refresh or a permission guidance message.

The approach to error handling in LWC and other frameworks such as React differs due to their distinct architectural models.

  • LWC: In addition to standard JavaScript error handling patterns, LWC provides an errorCallback(error, stack) lifecycle method in a parent component to catch errors from its children. When making @wire calls, errors are returned in an error object, which standardizes error handling in LWC.
  • React: Error handling typically relies on standard JavaScript mechanisms like promises for asynchronous Data SDK calls. You can also use error boundaries, which are special components (componentDidCatch, getDerivedStateFromError) that catch JavaScript errors in the component tree and display a fallback UI.

The error handling examples in the Multi-framework recipes repo demonstrate how to use error boundaries, handle GraphQL errors, and handle the loading, error, and empty states.