에러 코드 사전
연동 중 만날 수 있는 에러 코드와 원인, 해결 방법을 정리한 사전입니다.
연동 중 만나는 에러 코드와 원인, 해결 방법입니다. 브라우저로 돌아오는 에러는 콜백 주소의 쿼리스트링에, 토큰·API 에러는 JSON 본문에 담깁니다.
인증 요청 GET /oauth/authorize
| 코드 | 원인 | 해결 |
|---|---|---|
unsupported_response_type | response_type이 code가 아님 | response_type=code로 고정하세요. 다른 값은 지원하지 않습니다 |
invalid_request | client_id·redirect_uri·state 중 하나가 비어 있음 | 셋 다 필수입니다. 특히 state를 빠뜨리는 실수가 가장 흔합니다 |
pkce_required | code_challenge가 없음 | PKCE는 선택이 아니라 필수입니다. 5분 만에 붙이기 STEP 5 참고 |
invalid_code_challenge_method | code_challenge_method가 S256이 아님 | S256만 받습니다. plain은 지원하지 않습니다 |
unauthorized_client | client_id에 해당하는 클라이언트가 없음 | 마이페이지의 값을 그대로 복사했는지 확인하세요 |
invalid_scope | 스코프가 비었거나 허용 목록 밖 | 스코프 레퍼런스의 목록만 쓸 수 있습니다 |
insufficient_scope | 이 서비스에 부여되지 않은 스코프를 요청 | service.domain.read는 관리자 부여가 필요합니다 |
access_denied | 서비스나 클라이언트가 활성 상태가 아님 — 도메인 미인증, 콜백 미등록, 차단됨 | 마이페이지에서 서비스 상태를 확인하세요. «운영중»이어야 합니다 |
invalid_redirect_uri | redirect_uri가 등록된 콜백과 다름 | 문자 하나까지 정확히 같아야 합니다. 끝 슬래시, http/https, 포트까지 확인하세요 |
토큰 교환 POST /oauth/token
| 코드 | HTTP | 원인 · 해결 |
|---|---|---|
unsupported_grant_type | 400 | grant_type은 authorization_code 또는 refresh_token만 받습니다 |
invalid_request | 400 | 필수 파라미터 누락. code_verifier를 빠뜨렸는지 확인하세요 |
invalid_client | 401 | client_id/client_secret 불일치. secret을 다시 복사해 보세요 |
invalid_grant | 400 | 코드가 이미 사용됐거나 10분이 지났거나 존재하지 않음. 코드는 일회용입니다 |
invalid_grant+ pkce verification failed | 400 | code_verifier가 인증 요청 때 쓴 code_challenge와 맞지 않음. 세션에 저장한 값을 그대로 보내고 있는지 확인하세요 |
invalid_redirect_uri | 400 | 토큰 요청의 redirect_uri가 인증 요청 때와 다름. 두 번 다 같은 값을 보내야 합니다 |
server_error | 500 | 서버 내부 오류. 반복되면 문의해 주세요 |
사용자 정보 GET /oauth/userinfo · GET /oauth/domain-info
| 코드 | HTTP | 원인 · 해결 |
|---|---|---|
invalid_token | 401 | 토큰이 없거나, 만료(기본 1시간)됐거나, 폐기됨. refresh_token으로 새로 발급받으세요 |
insufficient_scope | 403 | /oauth/domain-info에는 service.domain.read가 필요합니다 |
자주 겪는 상황
«분명히 맞는데 계속 invalid_redirect_uri»
대부분 끝 슬래시입니다. 등록한 값이 https://예시.com/oauth/callback인데
요청에 https://예시.com/oauth/callback/을 넣으면 다른 값으로 취급합니다.
마이페이지에 등록된 문자열을 복사해서 붙여넣는 것이 가장 확실합니다.
«로그인은 되는데 email이 안 옵니다»
스코프 문제가 아닐 가능성이 높습니다. 이메일은 profile.basic에 포함돼 기본 제공되지만,
서비스별로 꺼둘 수 있습니다. 스코프 레퍼런스의 이메일 정책을 보세요.
«access_denied가 계속 납니다»
클라이언트가 아니라 서비스 상태를 확인하세요. 도메인 인증 완료 + 콜백 URL 등록 + 상태 «운영중» 이 세 가지가 모두 갖춰져야 인증 요청을 받습니다.