Error Codes

실패 응답 처리 기준

SSAFY Verify의 모든 public 실패 응답은 안전한 메시지, 안정적인 error_code, request_id를 포함합니다.

Verify/API error JSON

error.jsonVerify API와 일반 API 실패 응답

{
  "ok": false,
  "error": {
    "code": "LOGIN_CODE_INVALID",
    "message": "인증 코드가 만료되었습니다.",
    "request_id": "req_placeholder"
  }
}

OIDC v2 예정 error JSON

v1 신규 연동은 Verify/API error JSON만 사용합니다. 아래 형식은 향후 OIDC 로그인 연동을 공개할 때의 호환 형식입니다.

oauth-error.jsonOAuth 표준 error에 내부 error_code와 request_id 추가

{
  "error": "invalid_request",
  "error_description": "등록된 redirect URI와 일치하지 않습니다.",
  "error_code": "REDIRECT_URI_MISMATCH",
  "request_id": "req_placeholder"
}

Code table

사용자에게는 message와 request_id만 보여주고, 개발자 콘솔에는 error_code를 함께 남기세요.

Partner-local code

CALLBACK_ISSUER_MISMATCH는 SSAFY Verify public response가 아니라 외부 앱이 callback iss를 검증할 때 쓰는 권장 로컬 코드입니다.

INVALID_REQUESTLow

요청 형식이 올바르지 않습니다.

파라미터 이름, content-type, 필수 값을 확인

VALIDATION_FAILEDLow

입력값을 확인해주세요.

필드별 validation 결과와 요청 schema 확인

AUTH_REQUIREDMedium

로그인이 필요합니다.

사용자 세션 또는 관리자 권한 필요 여부 확인

CONSENT_DENIEDLow

사용자가 인증을 취소했습니다.

callback state를 유지하고 취소 UI 표시

USER_BLOCKEDHigh

사용할 수 없는 사용자입니다.

운영자에게 request_id와 사용자 식별자 전달

USER_NOT_VERIFIEDMedium

SSAFY 인증이 완료되지 않았습니다.

Verify 흐름을 처음부터 다시 시작

CLIENT_NOT_FOUNDHigh

등록되지 않은 앱입니다.

client_id와 환경변수 배포값 확인

CLIENT_PENDINGMedium

앱 승인을 기다리는 중입니다.

Developer Portal에서 승인 상태 확인

CLIENT_DISABLEDHigh

사용할 수 없는 앱입니다.

운영자에게 request_id와 client_id 전달

CLIENT_SECRET_INVALIDHigh

앱 인증 정보가 올바르지 않습니다.

서버 env의 secret과 재발급 이력 확인

REDIRECT_URI_MISMATCHHigh

등록된 callback 주소와 다릅니다.

배포 URL과 등록 URL을 exact match로 수정

SCOPE_NOT_ALLOWEDMedium

요청 권한이 승인되지 않았습니다.

client 승인 scope와 요청 scope 비교

PKCE_REQUIREDMedium

보안 검증 값이 누락되었습니다.

code_challenge와 method=S256 추가

PKCE_VERIFICATION_FAILEDHigh

보안 검증에 실패했습니다.

verifier 저장과 token exchange 전달 경로 확인

AUTHORIZATION_CODE_INVALIDHigh

인증 요청을 다시 시작해주세요.

code 재사용, 잘못된 client, redirect_uri 확인

AUTHORIZATION_CODE_EXPIREDMedium

인증 시간이 만료되었습니다.

사용자에게 인증 재시작 안내

AUTHORIZATION_CODE_USEDHigh

이미 사용된 인증 요청입니다.

중복 token exchange 또는 replay 가능성 확인

REFRESH_TOKEN_INVALIDHigh

다시 로그인해주세요.

refresh token 저장/rotation 상태 확인

REFRESH_TOKEN_REUSEDHigh

보안을 위해 다시 로그인해주세요.

refresh chain 폐기와 사용자 세션 재인증

VERIFY_TRANSACTION_NOT_FOUNDMedium

인증 요청이 만료되었습니다.

처음부터 Verify 흐름 재시작

VERIFY_TRANSACTION_EXPIREDMedium

인증 시간이 만료되었습니다.

사용자에게 Verify 흐름 재시작 안내

VERIFY_TRANSACTION_USEDHigh

이미 처리된 인증 요청입니다.

중복 callback 또는 replay 가능성 확인

LOGIN_CODE_INVALIDLow

인증 코드가 올바르지 않거나 만료되었습니다.

사용자에게 재입력 또는 재요청 안내

LOGIN_CODE_EXPIREDLow

인증 코드가 만료되었습니다.

코드 재발송 UX 제공

LOGIN_CODE_ATTEMPTS_EXCEEDEDMedium

입력 횟수를 초과했습니다.

처음부터 Verify 흐름 재시작

COHORT_UNAVAILABLEMedium

해당 기수 인증이 일시 중단되었습니다.

운영 공지와 대체 인증 여부 확인

COHORT_DEPRECATEDMedium

해당 기수 신규 인증이 종료되었습니다.

사용자에게 인증 불가 상태 안내

MATTERMOST_LOGIN_FAILEDHigh

인증 서버 연결에 실패했습니다.

대표 계정 credential과 기수 서버 상태 확인

MATTERMOST_TEAM_NOT_FOUNDHigh

기수 서버 정보를 찾을 수 없습니다.

cohort 설정의 team name과 base URL 확인

MATTERMOST_USER_NOT_FOUNDLow

Mattermost 사용자를 찾을 수 없습니다.

username 입력값과 기수 선택 확인

MATTERMOST_TEAM_MEMBERSHIP_REQUIREDMedium

해당 기수 구성원 확인이 필요합니다.

기수 서버 소속 여부 재확인

MATTERMOST_DM_FAILEDMedium

DM 발송에 실패했습니다.

운영자에게 request_id 전달

DATABASE_UNAVAILABLEHigh

잠시 후 다시 시도해주세요.

DB 연결, migration, connection pool 확인

CONFIGURATION_MISSINGHigh

서비스 설정이 완료되지 않았습니다.

운영 환경변수와 cohort/client 설정 확인

RATE_LIMITEDLow

요청이 많아 잠시 제한되었습니다.

잠시 후 재시도 안내

CALLBACK_ISSUER_MISMATCHLocal

인증 응답 출처를 확인할 수 없습니다.

외부 앱 로컬 검증 코드. callback iss와 issuer 설정 비교

UNEXPECTED_ERRORHigh

요청 처리 중 문제가 발생했습니다.

request_id로 운영 로그 조회 요청

request_id 사용법

사용자 실패 화면에는 request_id를 작게 표시합니다.
개발자는 request_id를 운영자에게 전달해 security event와 플랫폼 로그를 조회합니다.
token, code, client secret 원문은 문의 내용에 포함하지 않습니다.