rtk-query-html-guard
v1.0.2
Published
Detects HTML responses in RTK Query and converts PARSING_ERROR into a normalized, debuggable error.
Maintainers
olabisi09Readme
rtk-query-html-guard
Detect HTML responses in RTK Query and convert opaque parsing failures into a clear, normalized error.
When an API unexpectedly returns HTML (login redirect page, proxy error page, gateway timeout page), fetchBaseQuery may surface a generic PARSING_ERROR with little context. This package wraps your baseQuery and upgrades that case to a specific HTML_RESPONSE_ERROR you can handle intentionally.
Why this package exists
If your frontend expects JSON but receives HTML, you often see errors like:
SyntaxError: Unexpected token < in JSON at position 0- RTK Query
PARSING_ERROR
Those errors are common when:
- auth middleware redirects to an HTML login page
- reverse proxy/load balancer returns an HTML error page
- backend route is misconfigured and responds with HTML
This package helps you detect that condition reliably and handle it with clear logic.
Installation
npm install rtk-query-html-guardPeer dependency:
@reduxjs/toolkit^2.12.0
Quick start
import { fetchBaseQuery } from "@reduxjs/toolkit/query/react";
import { createHtmlGuardBaseQuery } from "rtk-query-html-guard";
const baseQuery = createHtmlGuardBaseQuery(fetchBaseQuery({ baseUrl: "/api" }));Use baseQuery in your API setup as usual:
import { createApi } from "@reduxjs/toolkit/query/react";
export const api = createApi({
reducerPath: "api",
baseQuery,
endpoints: (builder) => ({
getProfile: builder.query<{ id: string; name: string }, void>({
query: () => "/profile",
}),
}),
});What changes
Before wrapping:
{
status: "PARSING_ERROR",
originalStatus: 502,
data: "<!doctype html><html>..."
}After wrapping:
{
status: "HTML_RESPONSE_ERROR",
originalStatus: 502,
data: {
message:
"Expected JSON but received an HTML response. This usually means an auth redirect, gateway timeout, or misconfigured proxy.",
rawBodyPreview: "<!doctype html><html>..."
}
}Only this specific case is transformed. Successful responses and all other errors pass through unchanged.
Error type
export interface HtmlGuardError {
status: "HTML_RESPONSE_ERROR";
originalStatus: number | string;
data: {
message: string;
rawBodyPreview: string;
};
}Example error handling
const result = await baseQuery({ url: "/profile" }, api, extraOptions);
if ("error" in result && result.error?.status === "HTML_RESPONSE_ERROR") {
// Example: treat as session/auth infrastructure issue
console.error(result.error.data.message);
console.debug(result.error.data.rawBodyPreview);
}Exports
createHtmlGuardBaseQueryisHtmlResponseHtmlGuardError(TypeScript type)
How detection works
isHtmlResponse checks whether the raw response body is a string that starts with common HTML markers, for example <!doctype html>, <html>, <head>, <body>, and similar tags.
Notes
rawBodyPreviewis truncated to the first 300 characters.- This package does not alter successful JSON responses.
- This package only normalizes
PARSING_ERRORcases that look like HTML.
License
MIT