자주 묻는 질문
API 호출 중 오류가 발생했나요? 상태 코드로 문제를 빠르게 찾아보세요. 이 페이지에는 가장 일반적인 오류 코드와 해결 방법이 정리되어 있으며, 대부분의 문제는 1분 이내에 직접 해결할 수 있습니다.
빠른 문제 확인
코드에서 오류가 발생하면 먼저 HTTP 상태 코드(예: 401, 429)를 확인한 다음 아래 내용을 참고하세요:
| 상태 코드 | 원인 | 해결 방법 |
|---|---|---|
| 401 | API Key가 유효하지 않음 | 키 형식(sk-xxx)과 유효성 확인 |
| 402 | 잔액 부족 | 콘솔에서 충전 |
| 404 | 모델 ID 오류 | 모델 페이지에서 올바른 ID 복사 |
| 429 | 요청이 너무 빠름 | 요청 빈도를 낮추고 10초 후 다시 시도 |
| 500 | 업스트림 장애 | 잠시 후 다시 시도하거나 모델 전환 |
401 - API Key가 유효하지 않음
가장 일반적인 원인:
- 복사할 때 공백이 포함됨
- 형식이 잘못됨(
sk-로 시작하지 않음) - 키가 삭제됨
빠른 해결 방법:
# ✅ 올바른 형식
api_key = "sk-1234567890abcdef"
# ❌ 일반적인 오류
api_key = " sk-1234567890abcdef " # 앞뒤에 공백이 있음
api_key = "1234567890abcdef" # sk- 접두사 누락콘솔로 이동하여 키를 다시 복사하거나 새 키를 생성하세요.
402 - 잔액 부족
계정 잔액이 이번 요청을 결제하기에 부족합니다.
결제 센터로 이동하여 충전하세요.
주의: 긴 컨텍스트 요청(예: Gemini로 100만 tokens 처리)은 발생할 수 있는 최대 비용을 미리 차감하므로 잔액이 충분한지 확인하세요.
404 - 모델이 존재하지 않음
일반적인 원인:
- 모델 ID 철자 오류
- 이전 모델 이름 사용(예:
gpt-4o이gpt-6.1-sol로 대체됨) - Base URL 경로 오류
해결 방법:
올바른 모델 ID 가져오기
- 1
모델 페이지 방문
- 2
필요한 모델 찾기
검색하거나 찾아서 원하는 모델을 찾으세요
- 3
모델 ID 복사
복사 버튼을 클릭하거나 전체 ID를 직접 복사하세요
Base URL이 https://api.onemux.net/v1인지 확인하세요(끝에 /v1이 포함되어야 함)
429 - 요청이 너무 빠름
짧은 시간에 너무 많은 요청을 보내 빈도 제한이 적용되었습니다.
해결 방법:
- 요청 빈도 낮추기
- 10-30초 후 다시 시도
- 자동 재시도 로직 추가(오류 처리 문서 참고)
- 동시 작업 수 줄이기
500/502/503 - 서비스 장애
업스트림 모델 서비스를 일시적으로 사용할 수 없습니다.
해결 방법:
- 10-30초 후 다시 시도
- 다른 모델로 전환
- 상태 페이지에서 서비스 상태 확인
문제를 확실히 알 수 없을 때의 확인 순서
단계별 문제 확인
- 1
잔액 확인
콘솔에 로그인하여 잔액이 충분한지 확인
- 2
API Key 확인
전체 키를 다시 복사하고 공백이 없는지 확인
- 3
모델 ID 확인
모델 페이지에서 다시 복사
- 4
Base URL 확인
- 5
소프트웨어 재시작
설정을 저장한 후 클라이언트 재시작