Error Codes

실패 응답 처리 기준

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

QuickstartAI용 문서

Public API error JSON

error.jsonVerify API, Server API, 일반 API 실패 응답
{
  "ok": false,
  "error": {
    "code": "LOGIN_CODE_INVALID",
    "message": "인증 코드가 만료되었습니다.",
    "request_id": "req_placeholder"
  }
}

운영 로그 조회

request_id 추적

  • 운영자는 request_id로 Admin Console의 request_logs, security_events, audit_logs를 함께 조회합니다.
  • request_logs는 API 요청 로그를 영구 보존하며 IP address와 user-agent 원문을 포함합니다.
  • 요청/응답 body, bearer token, client secret, authorization header, raw Mattermost 응답은 로그에 저장하지 않습니다.

Code table

Verify API, Server API, Hosted SDK local code의 실패 처리 기준입니다.

Partner-local code

  • CALLBACK_ISSUER_MISMATCH는 SSAFY Verify public response가 아니라 외부 앱이 callback iss를 검증할 때 쓰는 권장 로컬 코드입니다.
  • SSAFY_VERIFY_* 코드는 Hosted SDK가 popup, preflight, timeout 단계에서 반환하는 browser-local code입니다.
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_OWNER_REQUIREDMedium

client 수정 권한이 없습니다.

Developer Portal 로그인 사용자와 client 소유자 확인

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 가능성 확인

VERIFY_CHALLENGE_CONTEXT_MISMATCHHigh

인증 요청이 변경되었습니다.

client_id, redirect_uri, state, PKCE challenge가 현재 popup 요청과 같은지 확인

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 전달

SERVER_TOKEN_INVALIDHigh

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

client_credentials secret, token aud, token_use, 만료 시간 확인

SERVER_SCOPE_NOT_ALLOWEDHigh

Server API 권한이 승인되지 않았습니다.

confidential client 승인 scope와 요청 scope 비교

PROFILE_NOT_FOUNDLow

프로필을 찾을 수 없습니다.

sub 또는 Mattermost user id 매핑과 scope 승인 상태 확인

PROFILE_SYNC_FAILEDMedium

프로필을 동기화하지 못했습니다.

Mattermost 연결 상태와 request_id 기준 운영 로그 확인

NOTIFICATION_TEMPLATE_NOT_APPROVEDMedium

승인되지 않은 알림 템플릿입니다.

Developer Portal template 요청 상태와 Admin Console 승인 여부 확인

NOTIFICATION_TARGET_NOT_FOUNDLow

알림 대상자를 찾을 수 없습니다.

sub 또는 ssafy_mattermost_user_id 저장 상태 확인

MATTERMOST_DELIVERY_FAILEDMedium

Mattermost 메시지를 전달하지 못했습니다.

delivery status와 request_id 기준 운영 로그 확인

IDEMPOTENCY_CONFLICTMedium

같은 키로 다른 요청을 보낼 수 없습니다.

client_id + idempotency_key payload 재사용 여부 확인

WEBHOOK_DELIVERY_FAILEDMedium

Webhook 전달에 실패했습니다.

endpoint URL, HMAC 검증, retry 로그 확인

DATABASE_UNAVAILABLEHigh

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

DB 연결, migration, connection pool 확인

CONFIGURATION_MISSINGHigh

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

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

RATE_LIMITEDLow

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

잠시 후 재시도 안내

CALLBACK_ISSUER_MISMATCHLocal

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

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

SSAFY_VERIFY_REDIRECT_URI_INVALIDLocal

인증 설정 URL이 올바르지 않습니다.

SDK redirectUri가 absolute URL인지 확인

SSAFY_VERIFY_REDIRECT_ORIGIN_MISMATCHLocal

현재 배포 URL과 callback URL이 다릅니다.

Local/Preview/Production redirect_uri를 각각 exact match로 등록

SSAFY_VERIFY_POPUP_BLOCKEDLocal

인증 창을 열 수 없습니다.

사용자 제스처 안에서 popup을 열고 브라우저 차단 여부 확인

SSAFY_VERIFY_POPUP_CLOSEDLocal

인증 창이 닫혔습니다.

사용자 취소와 구분해 재시도 버튼 제공

SSAFY_VERIFY_CALLBACK_TIMEOUTLocal

인증 응답을 받지 못했습니다.

callback 페이지 SDK 로드, postMessage, preview URL 등록 상태 확인

SSAFY_VERIFY_STATE_MISMATCHLocal

인증 요청 상태가 일치하지 않습니다.

state 보관 방식과 중복 popup 여부 확인

UNEXPECTED_ERRORHigh

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

request_id로 운영 로그 조회 요청

request_id 사용법

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