07 비동기 호출
7.3 API 에러 핸들링
비동기 API 호출을 하다 보면 상태 코드에 따라 401(인증되지 않은 사용자), 404(존재하지 않는 리소스), 500(서버 내부 에러) 혹은 CORS 에러 등 다양한 에러가 발생할 수 있다.
타입스크립트에서는 이러한 에러를 어떻게 처리하고 명시할 수 있는지 알아보자.
코드에서 발생할 수 있는 에러 상황에 대해 명시적인 코드를 작성하면 유지보수가 용이해지고, 사용자에게도 구체적인 에러 상황을 전달할 수 있다.
1. 타입 가드 활용하기
Axios 라이브러리에서는 Axios 에러에 대해 isAxiosError라는 타입 가드를 제공하고 있다.
이 타입 가드를 직접 사용할 수도 있지만, 서버 에러임을 명확하게 표시하고 서버에서 내려주는 에러 응답 객체에 대해서도 구체적으로 정의함으로써 에러 객체가 어떤 속성을 가졌는지를 파악할 수 있다.
다음과 같이 서버에서 전달하는 공통 에러 객체에 대한 타입을 정의할 수 있다.
interface ErrorResponse {
status: string;
serverDateTime: string;
errorCode: string;
errorMessage: string;
}
ErrorResponse 인터페이스를 사용하여 처리해야 할 Axios 에러 형태는 AxiosError
function isServerError(error: unknown): error is AxiosError<ErrorRespone> {
return axios.isAxiosError(error)
}
사용자 정의 타입 가드를 정의할 때는 타입 가드 함수의 반환 타입으로 parameterName is Type 형태의 타입 명제를 정의해주는 게 좋다.
이때 parameterName은 타입 가드 함수의 시그니처에 포함된 매개변수여야 한다.
const onClickDeleteHistoryButton = async (id: string) => {
try {
await axios.post('https://....', { id })
alert('주문 내역이 삭제되었습니다.')
} catch (error: unknown) {
if (isServerError(e) && e.response && e.response.data.errorMessage) {
// 서버 에러일 때의 처리임을 명시적으로 알 수 있다
setErrorMessage(e.response.data.errorMessage)
return
}
setErrorMessage('일시적인 에러가 발생했습니다. 잠시 후 다시 시도해주세요')
}
}
이처럼 타입 가드를 활용하면 서버 에러를 명시적으로 확인할 수 있다.
2. 에러 서브클래싱하기
실제 요청을 처리할 때 단순한 서버 에러도 발생하지만 인증 정보 에러, 네트워크 에러, 타임아웃 에러 같은 다양한 에러가 발생하기도 한다.
이를 더욱 명시적으로 표시하기 위해 서브클래싱을 활용할 수 있다.
서브클래싱(Subclassing)
기존(상위 또는 부모) 클래스를 확장하여 새로운(하위 또는 자식) 클래스를 만드는 과정을 말한다.
새로운 클래스는 상위 클래스의 모든 속성과 메서드를 상속받아 사용할 수 있고 추가적인 속성과 메서드를 정의할 수도 있다.
사용자에게 주문 내역을 보여주기 위해 서버에 주문 내역을 요청할 때는 다음과 같은 코드를 작성할 수 있다.
const getOrderHistory = async (page: number): Promise<History> => {
try {
const { data } = await axios.get(`https://some.site?page=${page}`)
const history = await JSON.parse(data)
return Promise.resolve(history)
} catch (error) {
alert(error.message)
return Promise.reject(error)
}
}
이 코드는 주문 내역을 요청할 때 에러가 발생하면 에러 메시지를 얼럿을 사용하여 사용자에게 표시해준다.
이때 “로그인 정보가 만료되었습니다.”, “유효하지 않은 요청 데이터입니다.”와 같이 서버에서 전달된 에러 메시지를 보고 사용자는 어떤 에러가 발생한 것인지 판단할 수 있더라도, 개발자 입장에서는 사용자 로그인 정보가 만료되었는지, 타임아웃이 발생한 건지 혹은 데이터를 잘못 전달한 것인지를 구분할 수 없다.
이때 서브클래싱을 활용하면 에러가 발생했을 때 코드상에서 어떤 에러인지를 바로 확인할 수 있다.
또한 에러 인스턴스가 무엇인지에 따라 에러 처리 방식을 다르게 구현할 수 있다.
class OrderHttpError extends Error {
private readonly privateResponse: AxiosResponse<ErrorResponse> | undefined
constructor(message?: string, response?: AxiosResponse<ErrorResponse>) {
super(message)
this.name = 'OrderHttpError'
this.privateResponse = response
}
get response(): AxiosResponse<ErrorResponse> | undefined {
return this.privateResponse
}
}
class NetworkError extends Error {
constructor(message = '') {
super(message)
this.name = 'NetworkError'
}
}
class UnauthorizedError extends Error {
constructor(message: string, response?: AxiosResponse<ErrorResponse>) {
super(message, response)
this.name = 'UnauthorizedError'
}
}
그다음 아래와 같이 에러 객체를 상속한 OrderHttpError, NetworkError, UnauthorizedError를 정의한다.
Axios를 사용하고 있다면 조건에 따라 인터셉터에서 적합한 에러 객체를 전달할 수 있다.
const httpErrorHandler = (
error: AxiosError<ErrorResponse> | Error
): Promise<Error> => {
let promiseError: Promise<Error>
if (axios.isAxiosError(error)) {
if (Object.is(error.code, 'ECONNABORTED')) {
promiseError = Promise.reject(new TimeoutError())
} else if (Object.is(error.message, 'Network Error')) {
promiseError = Promise.reject(new NetworkError(''))
} else {
const { response } = error as AxiosError<ErrorResponse>
switch (response?.status) {
case HttpStatusCode.UNAUTHORIZED:
promiseError = Promise.reject(
new UnauthorizedError(response?.data.message, response)
)
break
default:
promiseError = Promise.reject(
new OrderHttpError(response?.data.message, response)
)
}
}
} else {
promiseError = Promise.reject(error)
}
return promiseError
}
다시 요청 코드로 돌아와서 다음과 같이 활용할 수 있다.
const onActionError = (
error: unknown,
params?: Omit<AlertPopup, 'type' | 'message'>
) => {
if (error instanceof UnauthorizaedError) {
onUnauthorizedError(
error.message,
errorCallback?.onUnauthorizedErrorCallback
)
} else if (error instanceof NetworkError) {
alert('네트워크 연결이 원활하지 않습니다. 잠시 후 다시 시도해주세요.', {
onClose: errorCallback?.onNetworkErrorCallback,
})
} else if (error instanceof OrderHttpError) {
alert(error.message, params)
} else if (error instanceof Error) {
alert(error.message, params)
} else {
alert(defaultHttpErrorMessage, params)
}
}
const getOrderHistory = async (page: number): Promise<History> => {
try {
const { data } = await fetchOrderHistory({ page })
const history = await JSON.parse(data)
return history
} catch (error) {
onActionError(error)
}
}
이처럼 에러를 서브클래싱해서 표현하면 명시적으로 에러 처리를 할 수 있다.
error instanceof OrderHttpError와 같이 작성된 타입 가드문을 통해 코드상에서 에러 핸들링에 대한 부분을 한눈에 볼 수 있다.
3. 인터셉터를 활용한 에러 처리
Axios 같은 페칭 라이브러리는 인터셉터 기능을 제공한다.
이를 사용하면 HTTP 에러에 일관된 로직을 적용할 수 있다.
const httpErrorHandler = (
error: AxiosError<ErrorResponse> | Error
): Promise<Error> => {
(error) => {
// 401 에러인 경우 로그인 페이지로 이동
if (error.response && error.response.status === 401) {
window.location.href = `${backOfficeAuthHost}/login?targetUrl=${window.location.href}`
}
return Promise.reject(error)
}
}
orderApiRequester.interceptors.response.use(
(response: AxiosResponse) => response,
httpErrorHandler
)
4. 에러 바운더리를 활용한 에러 처리
에러 바운더리는 리액트 컴포넌트 트리에서 에러가 발생할 때 공통으로 에러를 처리하는 리액트 컴포넌트이다.
에러 바운더리를 사용하면 리액트 컴포넌트 트리 하위에 있는 컴포넌트에서 발생한 에러를 캐치하고, 해당 에러를 가장 가까운 부모 에러 바운더리에서 처리하게 할 수 있다.
에러 바운더리는 에러가 발생한 컴포넌트 대신에 에러 처리를 하거나 예상치 못한 에러를 공통 처리할 때 사용할 수 있다.
import React, { ErrorInfo } from 'react'
import ErrorPage from 'pages/ErrorPage'
interface ErrorBoundaryProps {}
interface ErrorBoundaryState {
hasError: boolean;
}
class ErrorBoundary extends React.Component<
ErrorBoundaryProps,
ErrorBoundaryState
> {
constructor(props: ErrorBoundaryProps) {
super(props)
this.state = { hasError: false }
}
static getDerivedStateFromError(): ErrorBoundaryState {
return { hasError: true }
}
componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
this.setState({ hasError: true })
console.error(error, errorInfo)
}
render(): React.ReactNode {
const { children } = this.props
const { hasError } = this.state
return hasError ? <ErrorPage /> : children
}
}
const App = () => {
return (
<ErrorBoundary>
<OrderHistoryPage />
</ErrorBoundary>
)
}
이처럼 작성하면 OrderHistoryPage 컴포넌트 내에서 처리되지 않은 에러가 있을 때 에러 바운더리에서 에러 페이지를 노출한다.
이외에도 에러 바운더리에 로그를 보내는 코드를 추가하여 예상치 못한 에러의 발생 여부를 추적할 수 있게 된다.
5. 상태 관리 라이브러리에서의 에러 처리
앞서 잠깐 살펴본 Redux의 에러 처리 방법은 다음과 같다.
// API 호출에 관한 api call reducer
const apiCallSlice = createSlice({
name: 'apiCall',
initialState,
reducers: {
setApiCall: (state, { payload: { status, urlInfo } }) => {
/* API State를 채우는 logic */
},
setApiCallError: (state, { payload }: PayloadAction<any>) => {
state.error = payload
},
},
})
const API = axios.create()
const setAxiosInterceptor = (store: EnhancedStore) => {
/* 중복 코드 생략 */
// onSuccess시 처리를 인터셉터로 처리한다
API.interceptors.response.use(
(response: AxiosResponse) => {
const { method, url } = response.config
store.dispatch(
setApiCall({
status: ApiCallStatus.None, // API 호출 상태를 `요청하지 않음`으로 변경
urlInfo: { url, method },
})
)
return response?.data?.data || response?.data
},
(error: AxiosError) => {
// 401 unauthorized
if (error.response?.status === 401) {
window.location.href = error.response.headers.location
return
}
// 403 forbidden
else if (error.response?.status === 403) {
window.location.href = error.response.headers.location
return
}
// 그 외에는 화면에 alert 띄우기
else {
message.error(`[서버 요청 에러]: ${error?.response?.data?.message}`)
}
const { config: {url, method}, } = error
store.dispatch(
setApiCall({
status: ApiCallStatus.None, // API 호출 상태를 `요청하지 않음`으로 변경
urlInfo: { url, method },
})
)
return Promise.reject(error)
}
)
}
에러 상태를 관리하지 않고 처리할 수 있다면 바로 처리(예: 401, 403)하고, 그렇지 않다면 reject로 넘겨준다.
이후 액션을 정의하면서 setApiCallError를 사용하여 에러를 상태로 처리한다.
const fetchMenu = createAsyncThunk(
FETCH_MENU_REQUEST,
async ({ shopId, menuId }: FetchMenu) => {
try {
const data = await api.fetchMenu(shopId, menuId)
return data
} catch (error) {
setApiCallError({ error })
}
}
)
이렇게 저장된 에러는 컴포넌트에서 사용할 수 있다.
만약 MobX를 사용하고 있다면 주로 스토어에서 에러 핸들링을 한다.
외부에서는 별도로 성공·실패 등에 대해 참조하지 않으며 비동기 동작의 수행 및 결괏값을 사용한다.
class JobStore {
jobs: Job[] = []
state: LoadingState = 'PENDING' // 'PENDING' | 'DONE' | 'ERROR'
errorMsg = ''
constructor() {
makeAutoObservable(this)
}
async fetchJobList() {
this.jobs = []
this.state = 'PENDING'
this.errorMsg = ''
try {
const projects = await fetchJobList()
runInAction(() => {
this.projects = projects
this.state = 'DONE'
})
} catch (e) {
runInAction(() => {
// 에러 핸들링 코드를 작성
this.state = 'ERROR'
this.errorMsg = e.message
showAlert()
})
}
}
get isLoading(): boolean {
return state === 'PENDING'
}
}
const jobList = (): JSX.Element => {
const [jobStore] = useState(() => new JobStore())
if (job.isLoading) {
return <Loader />
}
return <>{jobStore.jobs.map((job) => <Item job={job} />)}</>
}
6. react-query를 활용한 에러 처리
react-query나 swr과 같은 데이터 페칭 라이브러리를 사용하면 요청에 대한 상태를 반환해주기 때문에 요청 상태를 확인하기 쉽다.
const JobComponent: React.FC = () => {
const { isError, error, isLoading, data } = useFetchJobList()
if (isError) {
return <div>{`${error.message}가 발생했습니다. 나중에 다시 시도해주세요.`}</div>
}
if (isLoading) {
return <div>로딩 중입니다.</div>
}
return <>{data.map((job) => <JobItem key={job.id} job={job} />)}</>
}
7. 그 밖의 에러 처리
API 응답은 주로 성공 시 2xx 코드를, 실패 시 4xx, 5xx 코드를 반환한다.
일반적으로 API 요청 라이브러리에서도 HTTP 상태 코드에 따라 성공 응답인지 실패 응답인지를 판단한다.
그러나 비즈니스 로직에서의 유효성 검증에 의해 추가된 커스텀 에러는 200 응답과 함께 응답 바디에 별도의 상태 코드를 전달하기도 한다.
이러한 상황에서는 커스텀 에러를 어떻게 구현하고 처리할지에 대한 논의가 이루어질 수 있다.
하지만 이미 설계가 그렇게 되어있거나 레거시로 남아있지만 영향 범위가 넓어서 대응할 수 없을 때 등 200번 대의 성공 응답에 대한 에러 처리가 필요한 상황이 생길 수 있다.
예를 들어 장바구니에서 주문을 생성하는 API가 다음과 같은 커스텀 에러를 반환한다고 해보자.
httpStatus: 200
{
"status": "C20005", // 성공인 경우 "SUCCESS"를 응답
"message": "장바구니에 품절된 메뉴가 있습니다."
}
이 에러를 처리하기 위해 요청 함수 내에서 조건문으로 status를 비교할 수 있다.
const successHandler = (response: CreateOrderResponse) => {
if (response.status === 'SUCCESS') {
// 성공 시 진행할 로직을 추가한다
return
}
throw new CustomError(response.status, response.message)
}
const createOrder = (data: CreateOrderData) => {
try {
const response = apiRequester.post('https://...', data)
successHanlder(response)
} catch (error) {
errorHandler(error)
}
}
이 방법을 사용하면 간단하게 커스텀 에러를 처리할 수 있다.
또한 영향 범위가 각 요청에 대한 성공/실패 응답 처리 함수로 한정되어 관리하기 편리해진다.
그러나 이렇게 처리해야 하는 API가 많은 때는 매번 if (response.status === ‘SUCCESS’) 구문을 추가해야 한다.
만약 커스텀 에러를 사용하고 있는 요청을 일괄적으로 에러로 처리하고 싶다면 Axios 등의 라이브러리 기능을 활용하면 된다.
특정 호스트에 대한 API requester를 별도로 선언하고 상태 코드 비교 로직을 인터셉터에 추가할 수 있다.
export const apiRequester: AxiosInstance = axios.create({
baseURL: orderApiBaseUrl,
...defaultConfig,
})
export const httpSuccessHandler = (response: AxiosResponse) => {
if (response.data.status !== 'SUCCESS') {
throw new CustomError(response?.data.message, response)
}
return response
}
apiRequester.interceptors.response.use(httpSuccessHanlder, httpErrorHandler)
const createOrder = (data: CreateOrderData) => {
try {
const response = apiRequester.post('https://...', data)
successHandler(response)
} catch (error) {
// status가 SUCCESS가 아닌 경우 에러로 전달된다
errorHandler(error)
}
}
인터셉터에서 커스텀 에러를 판단하고 에러를 던짐으로써 외부에서 200번 대로 온 응답이라도 400번 대, 500번 대 같은 에러로 받게 된다.
이후 성공 핸들러에서는 성공인 경우의 동작만 작성하고, 에러 핸들러에서 커스텀 에러를 처리할 수 있다.