Google Search Console API 토큰 만료 — invalid_grant부터 권한 에러까지 해결 과정

상황

Python으로 Google Search Console API를 쓰는 자동화 스크립트를 만들었습니다. 처음엔 잘 됐는데 몇 달 후 실행하니 에러가 납니다.

google.auth.exceptions.RefreshError: ('invalid_grant: Token has been expired or revoked.', ...)

---

원인과 해결법 1 — token.json 삭제 후 재인증

OAuth 토큰은 영구적이지 않습니다. Google은 장기간 미사용 토큰, 보안 이벤트, 비밀번호 변경 등 여러 이유로 토큰을 만료시킵니다.

해결법은 간단합니다. token.json 파일을 삭제하고 다시 실행하면 브라우저 인증 창이 뜹니다.

# token.json이 있는 디렉토리에서
del token.json   # Windows
rm token.json    # Linux/Mac

python your_script.py  # 재실행하면 브라우저 열림

브라우저에서 Google 계정 로그인 → 권한 허용하면 새 token.json이 생성됩니다.

---

원인과 해결법 2 — Scope가 readonly인데 쓰기 작업을 하려고 할 때

사이트맵을 제출하거나 인덱싱 요청을 하려다 이런 에러가 납니다:

googleapiclient.errors.HttpError: <HttpError 403 when requesting ... returned "User does not have sufficient permission for this site.">

권한(scope)이 webmasters.readonly로 설정돼 있으면 읽기만 됩니다.

# 잘못된 설정 (읽기 전용)
GSC_SCOPE = ["https://www.googleapis.com/auth/webmasters.readonly"]

# 올바른 설정 (읽기 + 쓰기)
GSC_SCOPE = ["https://www.googleapis.com/auth/webmasters"]

scope를 바꾼 후에는 반드시 token.json을 삭제하고 재인증해야 합니다. 기존 토큰은 이전 scope로 발급된 거라 새 scope가 적용 안 됩니다.

---

원인과 해결법 3 — siteUrl 형식 문제

URL Inspection API 쓸 때 이런 에러:

HttpError 400: Request contains an invalid argument.

siteUrl에 trailing slash(끝에 /)가 없으면 안 됩니다.

# 잘못된 형식
site = "https://example.com"

# 올바른 형식
site = "https://example.com/"

Search Console에 등록한 속성 URL과 정확히 일치해야 합니다. https://와 http://도 구분하고, www 유무도 구분합니다.

---

원인과 해결법 4 — Windows에서 한글/이모지 출력 시 UnicodeEncodeError

GSC 데이터 출력하다가 한글이 포함된 키워드에서 터지는 경우:

UnicodeEncodeError: 'cp949' codec can't encode character

스크립트 상단에 추가:

import sys
import io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

---

전체 흐름 정리

GSC API 문제가 생겼을 때 체크리스트:

1. invalid_grant → token.json 삭제 후 재인증
2. 403 insufficient permission → scope를 webmasters로 변경 후 재인증
3. 400 invalid argument → siteUrl 끝에 / 붙었는지 확인
4. UnicodeEncodeError → stdout UTF-8 설정

scope를 바꿀 때마다 토큰 삭제 후 재인증이 필수입니다. 이걸 모르면 scope 바꿔도 왜 계속 같은 에러가 나는지 모릅니다.