가장 혈압 오르는 건 모델이 글을 못 쓰는 게 아니라, 막 시작하려는 순간 콘솔이 API key invalid, 401, network error 한 마디를 던지는 거다. 내가 제일 많이 빠졌던 함정은 이거였다: 키는 문제가 없는데 문제는 ‘주변 설정’에 있었다. 이 체크리스트는 내가 자주 쓰는 ChatGPT, Claude, Gemini 순서대로 정리했다.
먼저 올바른 Key와 올바른 프로젝트를 쓰고 있는지 확인
많은 사람이 예전 Key, 테스트 Key를 복사해 쓰거나, 콘솔에서 프로젝트를 바꿔 놓고도 신경 못 쓴다. 제공사 백오피스에서 Key를 새로 하나 만들고, 즉시 한 번 교체해서 써보는 걸 권한다. 구환경이랑 엉켜 싸우지 마라.
권한과 과금이 안 켜져 있으면 Key가 없는 것과 같다
401/403이 꼭 Key가 틀렸다는 뜻은 아니다. 흔한 원인은 과금 미개통, 권한 범위 부족, 조직/프로젝트 제한이다. Claude나 Gemini처럼 “겉보기엔 될 것 같은데” API만 치면 에러 나는 경우가 특히 흔하다. 어떻게 아느냐고 묻진 마라.
환경 변수와 공백은 숨은 킬러
.env에 공백이 하나 더 들어가거나, 개행 처리가 안 되었거나, 배포 플랫폼에 변수가 주입되지 않으면 전부 “Key 무효”로 변한다. Key 길이를 출력해 보고, 앞뒤를 trim해 보는 게 에러만 30분 바라보는 것보다 낫다.
