본문으로 건너뛰기
버전: 개발 버전 (최신)

Access Code 검증 API

회원가입 전에 Access Code의 유효성을 검증합니다.

  • HTTP Method: POST
  • Path: /de/v1/auth/access-code/validate
  • 인증: App Token 필요 (Authorization: Bearer {appToken})

Headers​

HeaderTypeDescriptionRequired
AuthorizationstringBearer {appToken} 형식Yes
Content-Typeapplication/json요청 본문 형식을 지정합니다.Yes

Request Body​

{
  "accessCode": "ABCD1234EFGH5678",
  "deviceId": "device-uuid-12345"
}
필드타입설명필수
accessCodestring검증할 16자리 Access CodeYes
deviceIdstringRate limiting을 위한 기기 고유 식별자Yes

Responses​

HTTP Status Code설명Error Code(s)
200 OK검증 성공-
400 Bad Request유효하지 않거나 만료된 Access Code3001, 3003
401 Unauthorized인증 실패 (App Token 오류)2051
409 Conflict이미 사용된 Access Code3002
429 Too Many RequestsAccess Code 검증 시도 횟수 제한 초과3045
500 Internal Server Error서버 내부 오류3000
200 OK - 검증 성공

Access Code가 유효하고 사용 가능할 경우 반환됩니다.

{
  "valid": true,
  "accessCodeId": "ac_123",
  "expiresAt": 1718949600000,
  "isUsed": false
}
필드타입설명필수
validbooleanAccess Code 유효 여부. 이 경우 항상 true입니다.Yes
accessCodeIdstringAccess Code의 고유 ID. 코드가 유효하고, 사용되지 않았으며, 만료되지 않은 경우 반환됩니다. (회원가입 시 사용 가능)No
expiresAtnumberAccess Code 만료 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64). 코드가 유효하고, 만료되지 않은 경우 반환됩니다.No
isUsedbooleanAccess Code 사용 여부. 코드가 유효한 경우, 일반적으로 false로 반환됩니다.No
400 Bad Request - 유효하지 않은 코드
{
  "code": 3001,
  "message": "INVALID_CODE",
  "detail": "유효하지 않은 Access Code입니다.",
  "metadata": {
    "remainingAttempts": 9 // 실패 후 남은 시도 횟수
  }
}
필드타입설명필수
codenumber애플리케이션 오류 코드 (3001, Kotlin: Int, Swift: Int)Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
metadata.remainingAttemptsnumber실패 후 남은 검증 시도 횟수 (Kotlin: Int, Swift: Int)Yes
400 Bad Request - 만료된 코드
{
  "code": 3003,
  "message": "CODE_EXPIRED",
  "detail": "만료된 Access Code입니다.",
  "metadata": {
    "remainingAttempts": 9 // 실패 후 남은 시도 횟수
  }
}
필드타입설명필수
codenumber애플리케이션 오류 코드 (3003)Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
metadata.remainingAttemptsnumber실패 후 남은 검증 시도 횟수 (Kotlin: Int, Swift: Int)Yes
409 Conflict - 이미 사용된 코드
{
  "code": 3002,
  "message": "CODE_ALREADY_USED",
  "detail": "이미 사용된 Access Code입니다.",
  "metadata": {
    "remainingAttempts": 9 // 실패 후 남은 시도 횟수
  }
}
필드타입설명필수
codenumber애플리케이션 오류 코드 (3002)Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
metadata.remainingAttemptsnumber실패 후 남은 검증 시도 횟수 (Kotlin: Int, Swift: Int)Yes
429 Too Many Requests - 시도 횟수 제한 초과
{
  "code": 3045,
  "message": "RATE_LIMIT_EXCEEDED",
  "detail": "요청 횟수가 제한을 초과했습니다. 잠시 후 다시 시도해주세요.",
  "metadata": {
    "remainingLockoutSeconds": 3599 // 잠금 해제까지 남은 시간(초)
  }
}
필드타입설명필수
codenumber애플리케이션 오류 코드 (3045, Kotlin: Int, Swift: Int)Yes
messagestring오류 메시지 코드Yes
detailstring사용자 친화적인 오류 설명Yes
metadata.remainingLockoutSecondsnumber잠금 해제까지 남은 시간 (초, Kotlin: Int, Swift: Int)Yes
401 Unauthorized - 인증 실패 (App Token 오류)

유효하지 않거나 만료된 appToken으로 요청 시 발생합니다. 이 경우는 검증 로직 이전에 발생하는 오류입니다.

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}
500 Internal Server Error - 서버 내부 오류

검증 과정 중 예상치 못한 서버 내부 오류 발생 시 반환될 수 있습니다.

{
  "code": 3000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

설명​

  • 이 API는 사용자가 회원가입 프로세스를 시작하기 전에 제공된 Access Code가 유효한지 확인하는 데 사용됩니다.
  • 유효한 appToken이 Authorization 헤더에 Bearer 토큰으로 포함되어야 합니다.
  • 검증 결과에 따라 적절한 HTTP 상태 코드와 응답 형식이 반환됩니다:
    • 성공 시: 200 OK와 valid: true 응답
    • 유효하지 않은 코드: 400 Bad Request와 표준 오류 응답
    • 만료된 코드: 400 Bad Request와 표준 오류 응답
    • 이미 사용된 코드: 409 Conflict와 표준 오류 응답
    • 시도 횟수 초과: 429 Too Many Requests와 표준 오류 응답
  • 성공 응답(valid: true) 시 반환되는 accessCodeId는 이후 회원가입 요청 시 사용될 수 있습니다.

오류 참조​

  • Access Code 관련 오류 코드:
    • 3001: INVALID_ACCESS_CODE (유효하지 않은 코드)
    • 3002: ACCESS_CODE_ALREADY_USED (이미 사용된 코드)
    • 3003: ACCESS_CODE_EXPIRED (만료된 코드)
    • 3045: RATE_LIMIT_EXCEEDED (요청 횟수 제한 초과)
  • 일반적인 인증/인가 관련 오류 코드(2000번대)는 Auth 도메인 오류 코드를 참조하세요.

공통 오류 응답 형식​

변경 이력​

버전날짜작성자변경 내용
0.1.02025-05-30elizabeth@weltcorp.com최초 문서 작성
0.2.02025-06-13elizabeth@weltcorp.com오류 코드 표준화 (2002 → 2051 INVALID_TOKEN)