Error Handling in Data SDK (Beta)

GraphQL can return both data and errors in the same response for queries or mutation operations that result in partial success. For example, the record operation succeeds, but some return fields aren’t accessible due to the user’s permission.

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. As the most conservative approach, it guarantees that the app processes data only when the request was entirely successful. Use this strategy with queries where incomplete data is misleading.

Data SDK preserves partial data from GraphQL error responses. When the server returns both data and errors, both fields are available in the result. This strategy allows you to gracefully degrade the UI by rendering the fetched data while logging errors for fields that failed.

Partial success responses where both data and errors are present aren’t cached. Each subsequent query re-fetches data from the network.

This strategy is suitable for cases where partial data is still usable by the app, even if the GraphQL request returns errors. The errors are logged for review, but the app 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 app to use any data that was successfully retrieved, even if partial errors occurred during the GraphQL request. The app throws an error only 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.

This example shows how to handle partial success in an update operation.

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.