React Query Server Action Errors

Goal

Do not throw expected user-facing errors from Server Actions. Return typed failure data. Throw only inside the client mutation when React Query needs an error.

Rules

• Return ActionResult<T, E> from Server Actions.
• Map raw server or API failures to safe error codes.
• Keep raw backend errors server-side.
• Translate error codes on the client.
• Throw a normal client-side Error from mutationFn for expected failures.
• Handle mutation errors close to the mutation or workflow.
• Do not set global mutation throwOnError: true.
• Use mutation-level throwOnError: true only for boundary fallback UI.