문서빠른 시작사이트 내 기본 튜토리얼
자주 발생하는 오류 코드
상태 코드를 마주쳤다면, 먼저 문제 유형을 판단한 뒤 우선순위에 따라 점검하세요
많은 사용자가 오류를 보면 바로 플랫폼 문제를 의심하지만, 실제로는 MoleAPI 연동 과정에서 발생하는 대부분의 오류는 상태 코드 + 설정 항목만으로도 빠르게 원인을 파악할 수 있습니다.
가장 권장하는 점검 순서
처음부터 전체 설정을 뒤엎지 마세요. 먼저 아래 순서대로 판단하는 것을 권장합니다.
- 먼저 상태 코드가 무엇인지 확인합니다
- 그다음 인증 문제인지, 권한 문제인지, 주소 문제인지, 요청 내용 문제인지 판단합니다
- 마지막으로 콘솔로 돌아가 해당 설정을 점검합니다
오류 코드 빠른 확인
| 상태 코드 | 일반적인 의미 | 우선적으로 확인해야 할 항목 |
|---|---|---|
| 400 | 요청 파라미터 오류 | JSON 구조, 필드 타입, 모델이 해당 파라미터를 지원하는지 여부 |
| 401 | 인증 실패 | API Key가 올바른지, 공백이 포함되지 않았는지, 만료되었는지 여부 |
| 403 | 권한 부족 | 모델 권한, Group, IP 화이트리스트, Key 한도 |
| 404 | 주소 또는 라우팅 오류 | Base URL이 올바른지, /v1이 누락되지 않았는지, 경로 오타 여부 |
| 429 | Rate Limit 또는 Quota 문제 | 요청 빈도, 동시성, 잔액, Quota 또는 한도 도달 여부 |
| 500 | 서버 측 예외 | 먼저 Retry하고 요청 정보를 보관한 뒤, 계속 발생하면 지원팀에 문의 |
상태 코드별 이해
400: 요청 자체에 문제가 있음
이 오류는 보통 다음을 의미합니다.
- 요청 구조가 올바르지 않음
- 특정 필드의 타입이 맞지 않음
- 모델이 지원하지 않는 파라미터를 전달함
최근에 모델을 바꿨거나, SDK를 교체했거나, 다른 사람의 예제 코드를 복사해 사용했다면 우선 이 부분부터 확인하세요.
401: API Key에 문제가 있음
우선적으로 확인할 항목:
- 입력한 값이 MoleAPI 콘솔에서 생성한
sk-...인지 - 앞뒤에 공백이 없는지
- 복사가 누락되거나 불완전하지 않은지
- 다른 플랫폼의 Key를 잘못 넣은 것은 아닌지
403: 인터페이스에는 접근 가능하지만 해당 작업 권한이 없음
이 오류는 다음 상황에서 가장 자주 발생합니다.
- 현재 Key에 해당 모델 권한이 없음
- 현재 Group이 이 모델을 지원하지 않음
- IP 화이트리스트를 설정했지만, 요청 출발 IP가 일치하지 않음
- Key 자체의 Quota 또는 제한이 트리거됨
404: 주소가 잘못됨
초보자가 가장 자주 겪는 문제 중 하나입니다.
우선적으로 확인할 항목:
- Base URL을
https://api.moleapi.com/v1로 입력했는지 - 여전히
api.openai.com으로 요청하고 있지 않은지 - 전체 API 경로를 Base URL에 잘못 입력한 것은 아닌지
429: 제한에 걸렸거나, Quota가 부족함
429를 봤을 때 단순히 “요청이 너무 빠르다”만 생각하지 말고, 아래 항목도 함께 확인해야 합니다.
- 잔액이 부족하지 않은지
- Key에 한도가 설정되어 있지 않은지
- 동시성이 너무 높지 않은지
- 짧은 시간 안에 요청이 지나치게 집중되지 않았는지
500: 서버 측 예외
간헐적으로 발생하는 경우 먼저 Retry해 볼 수 있습니다. 안정적으로 재현된다면 다음 정보를 보관하는 것을 권장합니다.
- 요청 시간
- 모델명
- 요청 파라미터
- Request ID(클라이언트에서 제공되는 경우)
이렇게 하면 이후 문제를 훨씬 더 빠르게 추적할 수 있습니다.
매우 실용적인 점검 순서 하나
어디서부터 시작해야 할지 모르겠다면, 아래 순서가 가장 시간을 절약합니다.
- 상태 코드 확인
- Base URL 확인
- API Key 확인
- 모델명 확인
- Group / 권한 / 한도 확인
- 잔액 및 로그 확인
경험 법칙
404는 대체로 먼저 주소를 확인하고, 401은 대체로 먼저 Key를 확인하며, 403은 대체로 먼저 권한을 확인하고, 429는 빈도뿐 아니라 잔액과 한도도 함께 확인해야 합니다.
다음으로 보면 좋은 문서
이 문서가 도움이 되었나요?
마지막 업데이트