---
name: API client error shape
description: How to read server error messages from the generated api-client-react fetch errors in frontend mutation/query handlers.
---

# Reading server errors on the frontend

The generated `@workspace/api-client-react` client (custom-fetch.ts) throws an
`ApiError` on non-2xx. The parsed response body is at **`err.data`** — NOT
`err.response.data` (axios-style). `ApiError` also exposes `err.response` (the
native `Response`, which has no `.data`), `err.status`, and `err.message`
(a prebuilt human string that already folds in `data.error`/`detail`/`message`).

Backend routes return errors as `{ error: "..." }`. So in React Query handlers:

```ts
onError: (err: unknown) => {
  const data = (err as { data?: { error?: string } })?.data;
  toast({ description: data?.error ?? "fallback", variant: "destructive" });
}
```

**Why:** writing `err.response?.data?.error` silently yields `undefined`
(native Response has no `.data`), so users always get the generic fallback and
real messages like "Insufficient wallet balance" never show.

**How to apply:** any frontend mutation/query onError that wants to surface the
server message must read `err.data?.error`, optionally falling back to
`err.message`.
