에러 응답

Connect Base API 의 에러 응답 형태와 HTTP 상태 코드 매핑입니다.

응답 형태

성공: 데이터 객체를 그대로 반환

json

{ "id": "row_abc", "data": { ... } }

기본 에러: 단순 형태 { "error": "..." }

json

{ "error": "잘못된 데이터 ID입니다." }

확장 에러 봉투 (push / workflow / template / function 등 일부 서비스):

json

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "월간 함수 호출 한도를 초과했습니다.",
    "details": { },
    "retryable": false,
    "suggestion": "콘솔에서 플랜을 업그레이드하세요"
  }
}

응답에 code 가 있다면 pkg/errs/errors.go 의 ErrorCode 상수 중 하나입니다(VALIDATION_ERROR, QUOTA_EXCEEDED, WORKFLOW_FAILED 등). 일관성을 위해 새로운 서비스는 봉투 형식을 사용하고, 기존 단순 형태는 점진적으로 마이그레이션 중입니다.

HTTP 상태 코드

상태	의미	일반적 원인
200	OK	성공
201	Created	리소스 생성 성공
400	Bad Request	요청 본문/파라미터 유효성 실패 (`VALIDATION_ERROR`)
401	Unauthorized	Public Key 누락 / 만료된 JWT (`UNAUTHORIZED`)
402	Payment Required	플랜 할당량(per-user) 초과 (`QUOTA_EXCEEDED`)
403	Forbidden	권한 부족 (예: `cb_pk_` 로 admin 엔드포인트 호출) (`FORBIDDEN`)
404	Not Found	잘못된 `tableId` / `storageId` / `functionId` (`NOT_FOUND`)
408	Request Timeout	함수 실행 타임아웃 (`TIMEOUT`)
409	Conflict	중복 키 / 이미 존재하는 리소스 (`CONFLICT`)
413	Payload Too Large	요청 본문 크기 초과 (`PAYLOAD_TOO_LARGE`)
422	Unprocessable Entity	스키마 검증 실패
429	Too Many Requests	분당 요청 제한 / rate limit (`RATE_LIMITED`)
500	Internal Server Error	서버 측 예외 (`INTERNAL_ERROR`)
503	Service Unavailable	의존 시스템 일시 오류 (`SERVICE_UNAVAILABLE` / `DEPENDENCY_ERROR`)

특수 에러 코드

코드	의미
`SCRIPT_NOT_FOUND`	game-server: `createRoom` 시 `scriptName` 으로 지정한 Lua 스크립트가 존재하지 않음
`rotation_failed`	auth: refresh token rotation 충돌 (replay 또는 동시 갱신, 재로그인 필요)
`BUILD_FAILED` / `DEPLOY_FAILED` / `TEST_FAILED`	함수 배포 파이프라인 단계별 실패
`WORKFLOW_FAILED` / `STEP_FAILED`	워크플로우 / 개별 step 실패
`TEMPLATE_ROLLBACK`	앱 템플릿 apply 실패 후 자동 롤백
`invalid_dpop_proof` / `use_dpop_nonce`	OAuth DPoP 표준 에러 (`/oauth/*` 엔드포인트)

📌 /v1/public/search 등 일부 엔드포인트는 cross-app row 가 섞이면 silent drop 후 빈 결과를 반환하고 별도 에러 코드를 노출하지 않습니다(테넌트 격리 보안 정책).

SDK 에서 처리

typescript

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

try {
  await cb.database.getData('tbl_xxx')
} catch (e) {
  if (e instanceof ApiError) {
    if (e.statusCode === 404) console.error('테이블을 찾을 수 없음')
    else if (e.statusCode === 429) console.error('Rate limit')
    else console.error('API 에러:', e.statusCode, e.message)
  } else if (e instanceof AuthError) {
    console.error('인증 에러:', e.message)
  }
}

자세한 패턴은 SDK 에러 처리 와 흔한 에러 & 해결책 을 참고하세요.

앱 템플릿 API

MCP 개요