쿼리 재시도

useQuery 쿼리가 실패하면(쿼리 함수가 오류를 발생시키면), 해당 쿼리의 요청이 최대 연속 재시도 횟수(기본값은 3)에 도달하지 않았거나 재시도 허용 여부를 결정하는 함수가 제공된 경우 TanStack Query가 쿼리를 자동으로 재시도합니다.

재시도는 전역 수준과 개별 쿼리 수준 모두에서 구성할 수 있습니다.

retry = false를 설정하면 재시도가 비활성화됩니다.
retry = 6을 설정하면 함수가 발생시킨 최종 오류를 표시하기 전에 실패한 요청을 6번 재시도합니다.
retry = true를 설정하면 실패한 요청을 무한히 재시도합니다.
retry = (failureCount, error) => ...을 설정하면 요청이 실패한 이유에 따라 사용자 지정 로직을 적용할 수 있습니다. 첫 번째 재시도에서 failureCount는 0부터 시작한다는 점에 유의하세요.

서버에서는 서버 렌더링을 최대한 빠르게 하기 위해 재시도의 기본값이 0입니다.

import { useQuery } from '@tanstack/react-query'

// Make a specific query retry a certain number of times
const result = useQuery({
  queryKey: ['todos', 1],
  queryFn: fetchTodoListPage,
  retry: 10, // Will retry failed requests 10 times before displaying an error
})

정보: error 속성의 내용은 마지막 재시도까지 useQuery의 failureReason 응답 속성에 포함됩니다. 따라서 위 예시에서 모든 오류 내용은 처음 9번의 재시도(총 10번의 시도) 동안 failureReason 속성에 포함되며, 모든 재시도 후에도 오류가 지속되면 마지막 시도 이후 최종적으로 error에 포함됩니다.

재시도 지연

기본적으로 TanStack Query의 재시도는 요청 실패 직후에 실행되지 않습니다. 일반적인 방식대로 각 재시도에 백오프 지연이 점진적으로 적용됩니다.

기본 retryDelay는 시도할 때마다 두 배로 늘어나도록(1000ms에서 시작) 설정되지만 30초를 초과하지 않습니다:

// Configure for all queries
import {
  QueryCache,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    },
  },
})

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}

권장하지는 않지만 Provider와 개별 쿼리 옵션 모두에서 retryDelay 함수/정수를 재정의할 수 있습니다. 함수 대신 정수로 설정하면 지연 시간은 항상 동일합니다:

const result = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodoList,
  retryDelay: 1000, // Will always wait 1000ms to retry, regardless of how many retries
})

백그라운드 재시도 동작

refetchIntervalInBackground: true와 함께 refetchInterval을 사용하면 브라우저 탭이 비활성 상태일 때 재시도가 일시 중지됩니다. 이는 재시도가 일반적인 다시 가져오기와 동일한 포커스 동작을 따르기 때문입니다.

백그라운드에서 계속 재시도해야 한다면 재시도를 비활성화하고 사용자 지정 다시 가져오기 전략을 구현하는 방안을 고려합니다:

const result = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  refetchInterval: (query) => {
    // Refetch more frequently when in error state
    return query.state.status === 'error' ? 5000 : 30000
  },
  refetchIntervalInBackground: true,
  retry: false, // Disable built-in retries
})

이 접근 방식을 사용하면 백그라운드에서 다시 가져오기를 활성 상태로 유지하면서 재시도 시점을 수동으로 제어할 수 있습니다.

재시도 지연​

백그라운드 재시도 동작​

재시도 지연

백그라운드 재시도 동작