Mock a REST API for RTK Query — the cache that doesn't refetch, the listener you forgot, and the error shape nobody expects

RTK Query is the data-fetching layer built into Redux Toolkit, and its top search queries are all variations of one confusion: "rtk query not refetching", "refetchOnFocus not working", "error.message is undefined". Almost none of these are bugs — they're cache policy, a missing one-liner, and an error shape that differs from axios. This guide pairs RTK Query with a hosted mock API whose failures you can script, and every number below was measured in a real Chrome on RTK Query 2.12.0 + React 18.3.1 (Vite, StrictMode on) with an instrumented window.fetch before publishing. Nothing here is folklore.

1. Try it in 10 seconds (no signup)

A shared, self-resetting demo project is live right now:

curl "https://mockbird.mockbird.workers.dev/m/demo/products?limit=3"

That URL is the API for every snippet below. CORS is open (Access-Control-Allow-Origin: *), so it works from localhost:5173, StackBlitz, or anywhere else. The whole API surface used in this guide:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

export const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: 'https://mockbird.mockbird.workers.dev/m/demo/' }),
  tagTypes: ['Products'],
  endpoints: b => ({
    getProducts: b.query({ query: p => 'products?' + p, providesTags: ['Products'] }),
    addProduct:  b.mutation({
      query: body => ({ url: 'products', method: 'POST', body }),
      invalidatesTags: ['Products'],
    }),
  }),
});
export const { useGetProductsQuery, useAddProductMutation } = api;

⚡ Skip the terminal: this link creates a live, seeded e-commerce backend (products, orders, customers, reviews) in the dashboard — real URL, no signup. Or import your own OpenAPI spec, db.json, CSV, Postman collection, or HAR and mock your exact shapes.

2. StrictMode: `useEffect` fetches twice, the hook fetches once

React 18 StrictMode double-mounts components in dev. Measured side by side in the same StrictMode app:

pattern	fetches observed (dev, StrictMode)
`useEffect(() => { fetch(…) }, [])`	2 — both mounts fetch
`useGetProductsQuery('limit=5')`	1 — the second mount subscribes to the in-flight cache entry

Measured: exactly 1 request, list rendered. RTK Query keys the cache by endpoint + serialized argument; the double mount is just a second subscription to the same entry, not a second request.

3. Five components, one request

Same mechanism, bigger payoff — call the hook wherever the data is needed instead of lifting state:

function Badge() {
  const { data } = useGetProductsQuery('limit=3');
  return <span>{data?.length ?? '…'}</span>;
}
// render five of them, side by side

Measured: 5 mounted components, 1 network request, all five rendered "3". Identical args → identical cache key → one fetch, five subscribers.

4. The error shape on a 500 — `error.status` + `error.data`, and no `.message`

Good news first: unlike a raw fetch (or SWR with a non-throwing fetcher), fetchBaseQuery treats any non-2xx response as an error automatically — you cannot accidentally render an error body as data. But the error object is not what axios habits expect:

const { data, error, isError } = useGetProductsQuery('limit=5&mock_status=500');

Measured with a forced 500: isError was true, data stayed undefined, and the error object was:

error.status  // 500                                        (number, or "FETCH_ERROR" for network failures)
error.data    // { "error": "simulated 500 error (mock_status)" }   ← the parsed response body
error.message // undefined — there is no .message on FetchBaseQueryError

If your error UI renders error.message, it renders blank. Render error.status and something from error.data instead — and because ?mock_status=<code> forces any status on any endpoint, you can render every error branch on purpose. Also measured: exactly 1 fetch — RTK Query does not retry by default (see §10 to add it).

5. All four UI states — each one reachable on demand

const { data, error, isLoading } = useGetProductsQuery(params);
if (isLoading)           return <Skeleton/>;
if (error)               return <ErrorBox status={error.status}/>;
if (data.length === 0)   return <EmptyState/>;
return <List items={data}/>;

params	what we observed
`mock_delay=2000&limit=5`	`isLoading` true during the real 2-second delay ("loading" on screen), then "data: 5"
`mock_status=500`	"error: 500" branch rendered
`category=nonexistent-cat`	`[]` → "empty" (the state everyone forgets to design)

More recipes: testing loading & error states.

6. "RTK Query is not refetching" — measured: that's the cache working as designed

The #1 confusion. Mount a list, navigate away (unmount), come back. SWR would revalidate; RTK Query serves the cache entry and does not touch the network:

Measured: mount → 1 fetch → unmount → remount = still 1 fetch total. The remounted list showed "4 items" instantly with zero requests — an unused cache entry lives for keepUnusedDataFor (default 60 seconds) and re-subscribing within that window is a pure cache hit, with no background revalidation. Your data isn't failing to refetch; it's cached on purpose. Three measured ways to change the policy:

knob	what we measured
`keepUnusedDataFor: 1` (per-endpoint or api-wide)	unmount, wait 2s, remount → 2 fetches — the entry expired, so remount refetched
`useGetProductsQuery(arg, { refetchOnMountOrArgChange: true })`	instant remount → 2 fetches — always refetch on subscribe (SWR-style freshness)
`invalidatesTags` on your mutations	the targeted fix — see §7

7. `invalidatesTags`: the mutation that refetches your list — exactly once

Tag invalidation is RTK Query's flagship feature: the mutation declares what it stales, subscribed queries refetch automatically. We measured it against a list that starts empty (writes persist on this API, so the refetched list really contains the new row):

getProducts: b.query({ query: p => 'products?' + p, providesTags: ['Products'] }),
addProduct:  b.mutation({
  query: body => ({ url: 'products', method: 'POST', body }),
  invalidatesTags: ['Products'],     // ← stales every getProducts subscription
}),

Measured: 1 initial GET (0 rows) → one addProduct() POST → exactly 1 automatic GET → list rendered 1 row, no manual refetch() anywhere. If your invalidatesTags "isn't working", the usual culprits are a tag string that doesn't match providesTags, or the mutation erroring before success (invalidation only fires on success — pair it with ?mock_status=500 and watch no refetch happen).

8. `refetchOnFocus` does nothing until you call `setupListeners`

The classic silent no-op. refetchOnFocus: true is a policy; the events come from setupListeners, and nothing warns you if you forgot it:

createApi({ ..., refetchOnFocus: true })          // policy: refetch when window regains focus

// the line everyone forgets, in store setup:
import { setupListeners } from '@reduxjs/toolkit/query';
setupListeners(store.dispatch);                   // ← wires focus/online events to the cache

Measured, same app, same focus event, only difference is the one line:

setup	fetches after window focus event
`refetchOnFocus: true`, no `setupListeners`	1 — the focus event is ignored; only the mount fetch ever happened
`refetchOnFocus: true` + `setupListeners(store.dispatch)`	2 — focus triggered a refetch

Same story for refetchOnReconnect. If tab-switching never refreshes your data, grep your store setup for setupListeners first.

9. `isLoading` vs `isFetching`, `data` vs `currentData` — why your page-2 spinner never shows

Change the query arg (page 1 → page 2, with a real 800 ms mock_delay) and read the flags mid-transition. Measured:

moment	isLoading	isFetching	data	currentData
first ever load (page 1)	true	true	`undefined`	`undefined`
mid page-1→2 transition	false	true	page-1 rows (first id 1)	`undefined`
page 2 landed	false	false	page-2 rows (first id 11)	page-2 rows

So: isLoading is only true for the first load of an endpoint — gate your page-transition spinner on isFetching. And data deliberately holds the previous page while the next one loads (built-in keep-previous-data), while currentData is undefined until the new arg's response lands — use currentData when showing stale rows would be wrong. Pagination pairs nicely with the X-Total-Count header this API exposes via CORS.

10. The stale-search race — keyed cache, zero AbortControllers

Type fast and a slow early response lands after a fast later one. We forced it: q=life with a real 3-second mock_delay, then switched the arg 300 ms later to q=way with no delay:

const { data } = useGetProductsQuery(`q=${q}`);   // the query IS the cache key

Measured: UI showed way: 7 within a second — and still way: 7 after the slow life response landed 3 seconds later. The stale response was filed under its own cache key; the hook only reads the key it's currently subscribed to, so the race can't clobber the UI. Two fetches, zero AbortControllers, zero cleanup code — the same win we measured for SWR and TanStack Query, because keyed caches make this bug structurally impossible.

11. `retry()` vs a scripted failure sequence

RTK Query ships a retry wrapper, off by default. ?mock_seq= serves a deterministic status sequence per key — "fails twice, then succeeds" becomes reproducible instead of hoped-for:

import { retry, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
baseQuery: retry(fetchBaseQuery({ baseUrl: BASE }), { maxRetries: 5 })

useGetProductsQuery('limit=3&mock_seq=503,503,200&mock_seq_key=run-42');

Measured: exactly 3 fetches — 503, 503, 200 — recovered in ~2.1 s. The observed gaps (752 ms, then 1299 ms) show the built-in exponential backoff with jitter. Use a fresh mock_seq_key per run so the sequence restarts. Chaos and jitter variants (?mock_chaos=, ?mock_jitter=) are in the docs.

12. `pollingInterval` actually polls

useGetProductsQuery('limit=1', { pollingInterval: 500 });

Measured: 6 fetches in 3.2 seconds — the rate you asked for. Worth stating because it's not a given: SWR's refreshInterval: 500 is silently throttled to 2 fetches in the same window by its default dedupingInterval (we measured that in the SWR guide). RTK Query has no such trap. Writes persist here, so POST a row mid-poll and watch the next tick pick it up. Related knob: skipPollingIfUnfocused (which, like §8, needs setupListeners to know about focus).

13. Optimistic update with a real rollback — `patchResult.undo()`

Optimistic UI is easy to demo when the write succeeds. The part worth testing is the rollback — so we forced the POST to fail with a real 500 (which this API treats as "server died before processing": the write is not applied, matching what a real outage does):

addOptimistic: b.mutation({
  query: body => ({ url: 'products?mock_status=500', method: 'POST', body }),
  async onQueryStarted(body, { dispatch, queryFulfilled }) {
    const patch = dispatch(api.util.updateQueryData('getProducts', 'limit=3',
      draft => { draft.push({ id: 'tmp', ...body }); }));   // draft is Immer — mutate away
    try { await queryFulfilled }
    catch { patch.undo(); }                                  // ← the rollback
  },
}),

Measured: the list rendered 3 rows → 4 rows (optimistic item visible) → back to 3 rows when the 500 landed. And verified server-side: the failed write really wasn't applied (a lookup for the optimistic row returned []), so a later refetch agrees with the rolled-back UI — no ghost row. Drop the mock_status param and the same code persists the row for real. Note the arg passed to updateQueryData must exactly match the query's arg — mismatched args are the silent-no-op version of this feature.

14. Get your own API (10 seconds, no signup)

curl -X POST https://mockbird.mockbird.workers.dev/api/projects \
  -H "Content-Type: application/json" \
  -d '{"preset": "ecommerce"}'

The response contains your project URL and admin key. Presets: blog, ecommerce, saas, payments — or define your own resources and field types, import an OpenAPI spec / db.json / CSV / Postman collection / HAR, and swap baseUrl in the createApi above. Ship day is an env-var change: VITE_API_URL=https://api.yourcompany.com.

There's a mock JWT login too — any email/password gets a real signed token from /auth/login, and /auth/me reads it back. Build the whole auth slice against it before an auth backend exists — guide.

15. Beyond this guide

Writes persist: POST/PATCH/DELETE actually stick (unlike JSONPlaceholder's write theater) — so invalidatesTags flows and optimistic rollbacks can be verified against reality.
TypeScript: GET /m/<project>/types.ts generates interfaces from your live schema (?format=zod for Zod schemas) — type your endpoints for free.
Snapshots: save a named data state, restore it in beforeEach — deterministic Playwright/Cypress runs (guide).
Rate limits: ?mock_ratelimit=5 gives you real 429s with Retry-After — see how retry() behaves under throttling.
GraphQL: the same data is queryable at /m/<project>/graphql if part of your app speaks GraphQL.

16. Honest comparison

Tool	Good at	Where this differs
TanStack Query	Same problem space without Redux; richer devtools ecosystem	If you're not already on Redux, it's usually the lighter choice — we have a TanStack Query guide too. If your app state lives in Redux, RTK Query's integration (one store, `createSlice` interop, tags) is the draw. The mock API side is identical.
SWR	Tiny API, great defaults for read-heavy UIs	Different freshness philosophy — SWR revalidates on mount by default, RTK Query serves cache (§6). Mutations and invalidation are hand-rolled in SWR, declarative here. Our SWR guide measures the same scenarios.
MSW (Mock Service Worker)	In-process request interception for unit tests; no network at all	MSW mocks live inside each test runner. Mockbird is a real hosted URL — the same mock serves your browser, CI, a StackBlitz repro, and a teammate's machine with zero setup. Use MSW for unit tests, a hosted mock for everything shared.
JSONPlaceholder	Instant, zero-setup, famous	Fixed dataset, writes are faked — `invalidatesTags` refetching after a POST just shows you the same list, and optimistic rollback can't be tested against write theater. Fine for a first tutorial; not for testing real flows.

Bias disclosure: this comparison is written by the Mockbird side. The measurements above, though, are just measurements — rerun them in your own Chrome with the snippets as written.

Mock a REST API for RTK Query — the cache that doesn't refetch, the listener you forgot, and the error shape nobody expects

1. Try it in 10 seconds (no signup)

2. StrictMode: useEffect fetches twice, the hook fetches once

3. Five components, one request

4. The error shape on a 500 — error.status + error.data, and no .message