코드로 ChatGPT, Claude, Gemini 인터페이스를 붙일 때 가장 미치게 하는 건 비즈니스 로직이 아니라, 시작하자마자 401/403/429를 툭 던져주는 겁니다. 급할 것 없어요. 이런 “API 키 오류”는 대부분 키가 진짜로 망가진 게 아니라, 설정 디테일이 사람을 놀리는 경우가 많습니다.
1 401 invalid_api_key 먼저 복사 방식을 의심
제가 가장 많이 본 사고: 키를 복사할 때 공백이 같이 들어가거나, 접두사가 빠지거나, 테스트 환경의 key를 운영에 넣는 경우. “최소 재현”을 하나 만들어 요청 한 줄만으로, 단순하게(KISS) 유지하세요. 비즈니스 로직 덩어리에서 바늘 찾지 마세요.
2 403 권한 부족 대부분은 프로젝트나 모델이 안 켜져 있음
Claude와 Gemini는 때로 권한을 프로젝트, 지역, 또는 모델 화이트리스트에 묶어두기도 합니다. 선택한 모델이 현재 Key에 대해 열려 있는지, 콘솔에 “API/결제 계정 활성화 필요” 같은 안내가 있는지 확인하세요.
3 429 rate limit 네 코드가 구린 게 아니라 할당량 또는 동시성 문제
429는 보통 두 가지: 요청이 너무 촘촘하거나, 쿼터를 다 쓴 경우. 재시도는 지수 백오프로 만들고, 겸사겸사 동시성 상한을 추가하면 바로 훨씬 나아집니다.
