에러 처리

SDK는 두 가지 에러 클래스를 export 합니다:

클래스	발생 상황	필드
`ApiError`	HTTP 응답이 4xx/5xx 일 때	`statusCode`, `message`, `name='ApiError'`
`AuthError`	인증/토큰 처리 단계에서 실패할 때	`message`, `name='AuthError'`

📌 SDK에는 ConnectBaseError 라는 클래스가 존재하지 않습니다. 위 두 클래스만 사용하세요.

기본 사용법

typescript

import ConnectBase, { ApiError, AuthError } from 'connectbase-client'

const cb = new ConnectBase({ publicKey: 'cb_pk_...' })

try {
  const result = await cb.database.getData('tbl_xxx')
} catch (e) {
  if (e instanceof ApiError) {
    console.error('API 에러:', e.statusCode, e.message)
  } else if (e instanceof AuthError) {
    console.error('인증 에러:', e.message)
  } else {
    throw e // 알 수 없는 에러는 그대로 던짐
  }
}

HTTP 상태 코드별 처리

statusCode	의미	일반적 원인
400	Bad Request	요청 본문/파라미터 유효성 실패
401	Unauthorized	Public Key 누락 / 만료된 JWT
403	Forbidden	권한 부족 (예: `cb_pk_` 로 admin 엔드포인트 호출)
404	Not Found	잘못된 `tableId` / `storageId` / `functionId`
409	Conflict	중복 키 / 이미 존재하는 리소스
429	Too Many Requests	플랜 한도 초과 (rate limit)
500	Internal Server Error	서버 측 예외
504	Gateway Timeout	빌드/배포 등 백엔드 내부 작업 타임아웃

typescript

try {
  await cb.auth.signInMember({ login_id, password })
} catch (e) {
  if (e instanceof ApiError) {
    switch (e.statusCode) {
      case 400:
      case 401:
        showError('아이디 또는 비밀번호가 올바르지 않습니다.')
        break
      case 404:
        showError('등록되지 않은 사용자입니다.')
        break
      case 429:
        showError('너무 많은 요청입니다. 잠시 후 다시 시도해주세요.')
        break
      default:
        showError('로그인 중 오류가 발생했습니다.')
    }
  }
}

글로벌 인증 에러 핸들러

SDK 초기화 옵션으로 인증 에러를 한 곳에서 처리할 수 있습니다.

typescript

const cb = new ConnectBase({
  publicKey: 'cb_pk_...',

  // 401 등 인증 실패가 발생할 때마다 호출
  onAuthError: (error) => {
    console.error('인증 실패:', error)
  },

  // refresh_token 까지 만료되어 재로그인이 필요할 때 호출
  onTokenExpired: () => {
    window.location.href = '/login'
  }
})

429 재시도 패턴

typescript

import { ApiError } from 'connectbase-client'

async function withRetry<T>(fn: () => Promise<T>, max = 3): Promise<T> {
  for (let i = 0; i < max; i++) {
    try {
      return await fn()
    } catch (e) {
      if (e instanceof ApiError && e.statusCode === 429 && i < max - 1) {
        await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000))
        continue
      }
      throw e
    }
  }
  throw new Error('재시도 한도 초과')
}

const result = await withRetry(() => cb.database.getData('tbl_xxx'))

함께 보기

흔한 에러 & 해결책 — 처음 연동할 때 자주 마주치는 에러들
인증 설정 — 토큰 갱신 흐름

에러 트래커 (Error Tracker)

API 개요