본문으로 건너뛰기
버전: 0.68.0

Questionnaire 관련 오류 코드

Questionnaire 도메인 또는 관련 API(예: /questionnaire/bundles, /questionnaire/versions)에서 발생할 수 있는 오류 코드입니다.

오류 응답 형식​

{
  "code": 9010,
  "message": "QUESTIONNAIRE_BUNDLE_NOT_FOUND",
  "detail": "설문지 번들을 찾을 수 없습니다",
  "metadata": {
    "bundleId": "bundle-123",
    "requestedVersion": "1.0.0"
  }
}
필드타입설명
codenumber애플리케이션 오류 코드
messagestring개발자용 오류 코드 이름 (대문자 및 언더스코어)
detailstring사용자에게 표시할 수 있는 친화적인 오류 메시지
errorsarray필드별 유효성 검증 오류가 있는 경우 추가 정보 제공 (선택 사항)
metadataobject오류 관련 추가 메타데이터 (선택 사항)
노트

errors와 metadata 필드는 선택 사항이며, 오류 상황에 따라 포함되지 않을 수 있습니다.

오류 코드 체계​

Questionnaire 관련 오류는 주로 9000번대 코드를 사용합니다.

범위용도
9000서버 및 일반 Questionnaire 오류
9010-9019설문지 번들 관련 오류
9020-9029설문지 버전 관련 오류
9030-9099향후 확장을 위한 예약 범위

서버 및 일반 오류 (9000)​

HTTP 상태 코드코드메시지설명
5009000SERVER_ERROR서버 내부 오류가 발생했습니다

설문지 번들 관련 오류 (9010-9019)​

설문지 번들의 조회, 관리 및 상태 검증 관련 오류입니다.

HTTP 상태 코드코드메시지설명
4049010QUESTIONNAIRE_BUNDLE_NOT_FOUND설문지 번들을 찾을 수 없습니다
4109011QUESTIONNAIRE_BUNDLE_EXPIRED설문지 번들이 만료되었습니다

설문지 버전 관련 오류 (9020-9029)​

설문지 버전의 조회, 관리 및 상태 검증 관련 오류입니다.

HTTP 상태 코드코드메시지설명
4049020QUESTIONNAIRE_VERSION_NOT_FOUND설문지 버전을 찾을 수 없습니다
4109021QUESTIONNAIRE_VERSION_EXPIRED설문지 버전이 만료되었습니다

오류 처리 가이드​

설문지 번들 오류 처리​

  • 설문지 번들을 찾을 수 없음(9010): 사용자에게 유효한 설문지 번들 ID를 확인하도록 안내하거나, 사용 가능한 번들 목록을 제공합니다.
  • 설문지 번들 만료(9011): 사용자에게 번들이 만료되었음을 알리고, 최신 버전의 번들을 사용하도록 안내합니다.

설문지 버전 오류 처리​

  • 설문지 버전을 찾을 수 없음(9020): 사용자에게 유효한 버전 정보를 확인하도록 안내하거나, 사용 가능한 버전 목록을 제공합니다.
  • 설문지 버전 만료(9021): 사용자에게 버전이 만료되었음을 알리고, 최신 버전을 사용하도록 안내합니다.

번들 및 버전 조회 오류 처리​

QUESTIONNAIRE_BUNDLE_NOT_FOUND (9010) 오류 발생 시:

{
  "code": 9010,
  "message": "QUESTIONNAIRE_BUNDLE_NOT_FOUND",
  "detail": "설문지 번들을 찾을 수 없습니다",
  "metadata": {
    "bundleId": "invalid-bundle-123",
    "availableBundles": ["bundle-001", "bundle-002", "bundle-003"],
    "suggestedAction": "사용 가능한 번들 목록에서 선택해주세요"
  }
}

클라이언트는 metadata.availableBundles 값을 확인하여 사용자에게 유효한 번들 옵션을 제시할 수 있습니다.

만료된 리소스 처리​

QUESTIONNAIRE_BUNDLE_EXPIRED (9011) 또는 QUESTIONNAIRE_VERSION_EXPIRED (9021) 오류 발생 시:

{
  "code": 9011,
  "message": "QUESTIONNAIRE_BUNDLE_EXPIRED",
  "detail": "설문지 번들이 만료되었습니다",
  "metadata": {
    "expiredAt": "2024-12-31T23:59:59Z",
    "latestVersion": "2.0.0",
    "migrationRequired": true
  }
}
  • HTTP 410 (Gone) 상태 코드를 사용하여 리소스가 영구적으로 사용 불가능함을 명시합니다.
  • metadata.latestVersion을 통해 사용자에게 최신 버전 정보를 제공합니다.
  • 필요한 경우 마이그레이션 가이드를 제공합니다.

설문지 생명주기 관리​

버전 관리 전략​

  • 하위 호환성: 이전 버전의 설문지도 일정 기간 동안 지원하여 점진적 마이그레이션을 허용합니다.
  • 만료 정책: 설문지 번들과 버전의 만료 일정을 사전에 공지하고, 충분한 마이그레이션 기간을 제공합니다.
  • 버전 추적: 각 설문지 버전의 사용 현황을 모니터링하여 안전한 만료 시점을 결정합니다.

캐싱 전략​

  • 번들 캐싱: 자주 사용되는 설문지 번들은 클라이언트 측에서 캐싱하여 성능을 향상시킵니다.
  • 버전 검증: 캐시된 버전이 만료되지 않았는지 주기적으로 검증합니다.
  • 자동 갱신: 만료 예정인 설문지에 대해 자동으로 최신 버전을 다운로드합니다.

모니터링 및 분석​

사용 패턴 분석​

  • 설문지 번들별 사용 빈도를 추적하여 인기 있는 설문지를 파악합니다.
  • 버전별 응답률을 분석하여 설문지 개선점을 도출합니다.
  • 만료된 설문지에 대한 접근 시도를 모니터링하여 마이그레이션 필요성을 평가합니다.

성능 최적화​

  • 설문지 로딩 시간을 모니터링하여 성능 병목점을 식별합니다.
  • 대용량 설문지 번들에 대한 분할 로딩 전략을 구현합니다.
  • CDN을 활용하여 설문지 리소스의 전 세계 배포를 최적화합니다.

변경 이력​

버전날짜작성자변경 내용
0.1.02025-01-20elizabeth@weltcorp.com최초 작성 - Questionnaire 도메인 오류 코드 문서화