openapi-react-query: Accessing http status code

[aidan-rypens]

Description

Currently, there is no way to access the http status code. What is the reasoning for this? Are there options to still access this?

Example:

Proposal

openapi-react-query.ts

Extra

• I’m willing to open a PR (see CONTRIBUTING.md)

[bluenote10]

I was about to open the same issue.

Without status code information, it isn't clear to me how to handle errors properly. Note that it doesn't make sense to assume that OpenAPI error specs are complete. For instance, an API may run behind a reverse proxy or load balancer, which can introduce errors like 502/503/504 on their part. The backend itself cannot know that, so it also cannot properly document every status code that a client can possibly see. Note that this is also acknowledged by the OpenAPI specs, stating:

Note that an API specification does not necessarily need to cover all possible HTTP response codes, since they may not be known in advance.

And even if an OpenAPI spec is complete, disambiguating the individual errors from the plain union type is problematic, and probably not generally possible?

For these reasons it feels essential to have access to the status code.

Note that there are a few related discussions:

• Switch error by status code #2092
• Handling error cases properly (openapi-fetch) #1618

Possibly related to:

• Ability to access response object in onError function #2257
• Possibility to access the response status code for "not ok" responses. #2238
• openapi-react-query: allow access to response headers #2127
• Access response when errors occur/transform error value and type #2231
• Differentiate between success and error for empty responses #2291

[aidan-rypens]

Correct. It is however possible with react-query.

The following includes the http status code in the response.

import {
  type UseMutationOptions,
  type UseMutationResult,
  type UseQueryOptions,
  type UseQueryResult,
  type InfiniteData,
  type UseInfiniteQueryOptions,
  type UseInfiniteQueryResult,
  type UseSuspenseQueryOptions,
  type UseSuspenseQueryResult,
  type QueryClient,
  type QueryFunctionContext,
  type SkipToken,
  useMutation,
  useQuery,
  useSuspenseQuery,
  useInfiniteQuery,
} from '@tanstack/react-query';
import type {
  ClientMethod,
  FetchResponse,
  MaybeOptionalInit,
  Client as FetchClient,
  DefaultParamsOption,
} from 'openapi-fetch';
import type {
  HttpMethod,
  MediaType,
  PathsWithMethod,
  RequiredKeysOf,
} from 'openapi-typescript-helpers';

// Helper type to dynamically infer the type from the `select` property
type InferSelectReturnType<TData, TSelect> = TSelect extends (
  data: TData,
) => infer R
  ? R
  : TData;

type InitWithUnknowns<Init> = Init & { [key: string]: unknown };

export type QueryKey<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Method extends HttpMethod,
  Path extends PathsWithMethod<Paths, Method>,
  Init = MaybeOptionalInit<Paths[Path], Method>,
> = Init extends undefined
  ? readonly [Method, Path]
  : readonly [Method, Path, Init];

export type QueryOptionsFunction<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Media extends MediaType,
> = <
  Method extends HttpMethod,
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
  Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, // note: Required is used to avoid repeating NonNullable in UseQuery types
  Options extends Omit<
    UseQueryOptions<
      Response['data'],
      Response['error'],
      InferSelectReturnType<Response['data'], Options['select']>,
      QueryKey<Paths, Method, Path>
    >,
    'queryKey' | 'queryFn'
  >,
>(
  method: Method,
  path: Path,
  ...[init, options]: RequiredKeysOf<Init> extends never
    ? [InitWithUnknowns<Init>?, Options?]
    : [InitWithUnknowns<Init>, Options?]
) => NoInfer<
  Omit<
    UseQueryOptions<
      Response['data'],
      Response['error'],
      InferSelectReturnType<Response['data'], Options['select']>,
      QueryKey<Paths, Method, Path>
    >,
    'queryFn'
  > & {
    queryFn: Exclude<
      UseQueryOptions<
        Response['data'],
        Response['error'],
        InferSelectReturnType<Response['data'], Options['select']>,
        QueryKey<Paths, Method, Path>
      >['queryFn'],
      SkipToken | undefined
    >;
  }
>;

export type UseQueryMethod<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Media extends MediaType,
> = <
  Method extends HttpMethod,
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
  Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, // note: Required is used to avoid repeating NonNullable in UseQuery types
  Options extends Omit<
    UseQueryOptions<
      Response['data'],
      Response['error'],
      InferSelectReturnType<Response['data'], Options['select']>,
      QueryKey<Paths, Method, Path>
    >,
    'queryKey' | 'queryFn'
  >,
>(
  method: Method,
  url: Path,
  ...[init, options, queryClient]: RequiredKeysOf<Init> extends never
    ? [InitWithUnknowns<Init>?, Options?, QueryClient?]
    : [InitWithUnknowns<Init>, Options?, QueryClient?]
) => UseQueryResult<
  InferSelectReturnType<Response['data'], Options['select']>,
  Response['error']
> & {
  httpStatusCode?: number;
  httpStatusCodeText?: string;
};

export type UseInfiniteQueryMethod<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Media extends MediaType,
> = <
  Method extends HttpMethod,
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
  Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>,
  Options extends Omit<
    UseInfiniteQueryOptions<
      Response['data'],
      Response['error'],
      InferSelectReturnType<InfiniteData<Response['data']>, Options['select']>,
      Response['data'],
      QueryKey<Paths, Method, Path>,
      unknown
    >,
    'queryKey' | 'queryFn'
  > & {
    pageParamName?: string;
  },
>(
  method: Method,
  url: Path,
  init: InitWithUnknowns<Init>,
  options: Options,
  queryClient?: QueryClient,
) => UseInfiniteQueryResult<
  InferSelectReturnType<InfiniteData<Response['data']>, Options['select']>,
  Response['error']
>;

export type UseSuspenseQueryMethod<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Media extends MediaType,
> = <
  Method extends HttpMethod,
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
  Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, // note: Required is used to avoid repeating NonNullable in UseQuery types
  Options extends Omit<
    UseSuspenseQueryOptions<
      Response['data'],
      Response['error'],
      InferSelectReturnType<Response['data'], Options['select']>,
      QueryKey<Paths, Method, Path>
    >,
    'queryKey' | 'queryFn'
  >,
>(
  method: Method,
  url: Path,
  ...[init, options, queryClient]: RequiredKeysOf<Init> extends never
    ? [InitWithUnknowns<Init>?, Options?, QueryClient?]
    : [InitWithUnknowns<Init>, Options?, QueryClient?]
) => UseSuspenseQueryResult<
  InferSelectReturnType<Response['data'], Options['select']>,
  Response['error']
> & {
  httpStatusCode?: number;
  httpStatusCodeText?: string;
};

export type UseMutationMethod<
  Paths extends Record<string, Record<HttpMethod, {}>>,
  Media extends MediaType,
> = <
  Method extends HttpMethod,
  Path extends PathsWithMethod<Paths, Method>,
  Init extends MaybeOptionalInit<Paths[Path], Method>,
  Response extends Required<FetchResponse<Paths[Path][Method], Init, Media>>, // note: Required is used to avoid repeating NonNullable in UseQuery types
  Options extends Omit<
    UseMutationOptions<Response['data'], Response['error'], Init>,
    'mutationKey' | 'mutationFn'
  >,
>(
  method: Method,
  url: Path,
  options?: Options,
  queryClient?: QueryClient,
) => UseMutationResult<Response['data'], Response['error'], Init> & {
  httpStatusCode?: number;
  httpStatusCodeText?: string;
};

export interface OpenapiQueryClient<
  Paths extends {},
  Media extends MediaType = MediaType,
> {
  queryOptions: QueryOptionsFunction<Paths, Media>;
  useQuery: UseQueryMethod<Paths, Media>;
  useSuspenseQuery: UseSuspenseQueryMethod<Paths, Media>;
  useInfiniteQuery: UseInfiniteQueryMethod<Paths, Media>;
  useMutation: UseMutationMethod<Paths, Media>;
}

export type MethodResponse<
  CreatedClient extends OpenapiQueryClient<any, any>,
  Method extends HttpMethod,
  Path extends CreatedClient extends OpenapiQueryClient<
    infer Paths,
    infer _Media
  >
    ? PathsWithMethod<Paths, Method>
    : never,
  Options = object,
> =
  CreatedClient extends OpenapiQueryClient<
    infer Paths extends { [key: string]: any },
    infer Media extends MediaType
  >
    ? NonNullable<FetchResponse<Paths[Path][Method], Options, Media>['data']>
    : never;

export default function createClient<
  Paths extends {},
  Media extends MediaType = MediaType,
>(client: FetchClient<Paths, Media>): OpenapiQueryClient<Paths, Media> {
  const queryFn = async <
    Method extends HttpMethod,
    Path extends PathsWithMethod<Paths, Method>,
  >({
    queryKey: [method, path, init],
    signal,
  }: QueryFunctionContext<QueryKey<Paths, Method, Path>>) => {
    const mth = method.toUpperCase() as Uppercase<typeof method>;
    const fn = client[mth] as ClientMethod<Paths, typeof method, Media>;
    const { data, response } = await fn(path, {
      signal,
      ...(init as any),
    });
    const processedData =
      response.status === 204 || response.headers.get('Content-Length') === '0'
        ? (data ?? null)
        : data;

    return {
      _originalData: processedData,
      _httpStatusCode: response.status,
      _httpStatusCodeText: response.statusText,
    } as any;
  };

  const queryOptions: QueryOptionsFunction<Paths, Media> = (
    method,
    path,
    ...[init, options]
  ) => ({
    queryKey: (init === undefined
      ? ([method, path] as const)
      : ([method, path, init] as const)) as QueryKey<
      Paths,
      typeof method,
      typeof path
    >,
    queryFn,
    ...options,
  });

  return {
    queryOptions,
    useQuery: (method, path, ...[init, options, queryClient]) => {
      const result = useQuery(
        queryOptions(
          method,
          path,
          init as InitWithUnknowns<typeof init>,
          options,
        ),
        queryClient,
      );
      return {
        ...result,
        data: (result.data as any)?._originalData,
        httpStatusCode: (result.data as any)?._httpStatusCode,
        httpStatusCodeText: (result.data as any)?._httpStatusCodeText,
      };
    },
    useSuspenseQuery: (method, path, ...[init, options, queryClient]) => {
      const result = useSuspenseQuery(
        queryOptions(
          method,
          path,
          init as InitWithUnknowns<typeof init>,
          options,
        ),
        queryClient,
      );
      return {
        ...result,
        data: (result.data as any)?._originalData,
        httpStatusCode: (result.data as any)?._httpStatusCode,
        httpStatusCodeText: (result.data as any)?._httpStatusCodeText,
      };
    },
    useInfiniteQuery: (method, path, init, options, queryClient) => {
      const { pageParamName = 'cursor', ...restOptions } = options;
      const { queryKey } = queryOptions(method, path, init);
      return useInfiniteQuery(
        {
          queryKey,
          queryFn: async ({
            queryKey: [method, path, init],
            pageParam = 0,
            signal,
          }) => {
            const mth = method.toUpperCase() as Uppercase<typeof method>;
            const fn = client[mth] as ClientMethod<Paths, typeof method, Media>;
            const mergedInit = {
              ...init,
              signal,
              params: {
                ...(init?.params || {}),
                query: {
                  ...(init?.params as { query?: DefaultParamsOption })?.query,
                  [pageParamName]: pageParam,
                },
              },
            };

            const { data, error } = await fn(path, mergedInit as any);
            if (error) {
              throw error;
            }
            return data;
          },
          ...restOptions,
        },
        queryClient,
      );
    },
    useMutation: (method, path, options, queryClient) =>
      useMutation(
        {
          mutationKey: [method, path],
          mutationFn: async (init) => {
            const mth = method.toUpperCase() as Uppercase<typeof method>;
            const fn = client[mth] as ClientMethod<Paths, typeof method, Media>;
            const { data, error } = await fn(
              path,
              init as InitWithUnknowns<typeof init>,
            );
            if (error) {
              throw error;
            }

            return data as Exclude<typeof data, undefined>;
          },
          ...options,
        },
        queryClient,
      ),
  };
}

[kaaax0815]

Is there any update on this?

[krav4enkodm]

We ran into the same issue with openapi-react-query@0.5.4 + openapi-fetch@0.17.0. The error thrown by useQuery/useMutation is just the parsed response body — the Response object (and its status) is discarded in the queryFn.
Workaround: openapi-fetch middleware that enriches error bodies with the status code

import type { Middleware } from 'openapi-fetch'

const errorStatusMiddleware: Middleware = {
  async onResponse({ response }) {
    if (!response.ok) {
      try {
        const body = await response.json()
        return new Response(
          JSON.stringify({
            ...body,
            statusCode: response.status,
          }),
          {
            status: response.status,
            statusText: response.statusText,
            headers: response.headers,
          },
        )
      } catch {
        return response
      }
    }
    return undefined
  },
}

Register it on your fetch client:

const fetchClient = createClient<paths>({
  baseUrl: '...',
})
fetchClient.use(errorStatusMiddleware)

Then in your component the error object from useQuery will have statusCode alongside the original fields:

const { data, error } = api.useQuery('get', '/resource/{id}', { params: { path: { id } } })

if (error?.statusCode === 404) {
  // handle not found
}

Notes:

• Using statusCode instead of status to avoid collisions with API response fields named status.
• The try/catch handles edge cases where the body isn't JSON or the stream was already consumed by another middleware.
• Place this middleware after any token-refresh middleware (which intercepts 401s), so it doesn't interfere with retry logic.

That said, this is a workaround — it would be great to have first-class access to the Response (or at least the status code) on the error object from useQuery/useMutation. The queryFn in openapi-react-query already has access to { data, error, response } from the fetch client; it just needs to preserve response (or response.status) when throwing.