Document how to handle errors for resumed mutations

Author: djhi

docs/DataProviders.md

@@ -1017,4 +1017,41 @@ queryClient.setMutationDefaults('banUser', {
         return dataProvider.banUser(userId);
     },
 });
-```
+```
+
+## Handling Errors For Resumed Mutations
+
+If you enabled offline support, users might trigger mutations while being actually offline. When they're back online, react-query will _resume_ those mutations and they might fail for other reasons (server side validation or errors). However, as users might have navigated away from the page that triggered the mutation, they won't see any notification.
+
+To handle this scenario, you must register default `onError` side effects for all mutations (react-admin default ones or custom). If you want to leverage react-admin notifications, you can use a custom layout:
+
+```tsx
+// in src/Layout.tsx
+export const MyLayout = ({ children }: { children: React.ReactNode }) => {
+    const queryClient = useQueryClient();
+    const notify = useNotify();
+
+    React.useEffect(() => {
+        const mutationKeyFilter = []; // An empty array targets all mutations 
+        queryClient.setMutationDefaults([], {
+            onSettled(data, error) {
+                if (error) {
+                    notify(error.message, { type: 'error' });
+                }
+            },
+        });
+    }, [queryClient, notify]);
+
+    return (
+        <Layout>
+            {children}
+        </Layout>
+    );
+}
+```
+
+Note that this simple example will only show the error message as it was received. Users may not have the context to understand the error (what record or operation it relates to).
+Here are some ideas for a better user experience:
+
+- make sure your messages allow users to go to the pages related to the errors (you can leverage [custom notifications](./useNotify.md#custom-notification-content) for that)
+- store the notifications somewhere (server side or not) and show them in a custom page with proper links, etc.