thunkAPIrejectWithValuereserror

ThunkAPI.rejectWithValue is a utility provided by Redux Toolkit's createAsyncThunk. It is part of the thunkAPI object passed to the payload creator function and is used to dispatch a rejected action with a custom payload. The thunkAPI object also includes other helpers such as dispatch, getState, extra, requestId, and signal.

The primary purpose of rejectWithValue is to propagate structured error information from an async operation. When you return rejectWithValue(someValue), the resulting rejected action carries someValue in its payload. This allows reducers and UI code to access a precise error payload (for example, server-provided validation errors) instead of a generic error message.

Common usage involves catching an error from an async operation and, when useful data is available, calling rejectWithValue with that data. For example, after a failed API call that returns a detailed error body, you would return rejectWithValue(errorData) instead of throwing. If no useful payload is available, you can fall back to throwing the error to trigger a standard rejection.

In reducers, handling a rejected action typically checks action.payload first. If a payload exists, it represents the error details you intended to surface to the UI. If there is no payload, you fall back to action.error?.message or another generic indicator. This pattern helps produce more informative user feedback while keeping error handling centralized.

Overall, rejectWithValue provides a controlled way to surface structured, known errors from asynchronous thunks, improving error reporting without sacrificing the benefits of createAsyncThunk’s automatic lifecycle actions.