Qwen API 문제 해결: 401 / 404 / 429 / 503 / 타임아웃 구분하기
Qwen API 문제 해결
OpenAI 호환 엔드포인트를 호출할 때 가장 시간을 낭비하는 경우는 "에러 코드는 보이는데 뭘 고쳐야 할지 모르는" 상태입니다. 401, 404, 429, 503, 타임아웃 — 원인이 각각 다르므로 무작정 시도하지 말고 정해진 순서로 구분합니다. 이 글은 Qwen 계열을 포함한 모델 호출 전반에 쓸 수 있는 절차입니다.
30초 요약
진단 순서는 고정: ① Key ② URL ③ 모델 ID ④ 서비스 상태. 먼저 curl로 최소 요청을 보내 원시 HTTP 상태와 응답 본문을 확인합니다. 401은 Key, 404는 URL 경로, model-not-found는 ID, 429는 백오프 재시도, 503은 횟수 제한 재시도, 타임아웃은 네트워크와 요청 크기 확인.
먼저 curl로 최소 요청 보내기
비즈니스 코드를 만지기 전에 최소 재현 요청을 curl로 실행합니다. SDK는 오류를 감싸 원래 응답을 숨길 수 있으므로, 원시 상태 코드와 본문이 보이는 curl이 가장 확실합니다.
curl -sS https://exaiv.com/api/ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "kimi-k3",
"messages": [{"role": "user", "content": "hi"}]
}'
모델 ID는 /models 디렉터리의 실시간 정보를 따르세요. HuggingFace 가중치 이름을 넣으면 요청은 통과하지 않습니다.
401: Key 또는 인증 헤더
401 Unauthorized는 인증되지 않았다는 뜻입니다. 흔한 3가지 원인:
| 원인 | 확인 항목 |
|---|---|
| Key 무효·형식 불량 | 완전히 복사했는지, 앞뒤 공백, 만료 여부 |
| 헤더 형식 불량 | Authorization: Bearer 접두사가 있는지 |
| 계정 불일치 | 콘솔의 Key가 현재 사이트 것인지 |
최소 복구 절차: Key를 재생성하고 앞뒤 공백 없이 붙여넣은 뒤 curl을 다시 실행합니다.
Bearer 접두사를 잊지 마세요
Authorization 헤더 값은 Key 자체가 아니라 Bearer <Key>입니다. 접두사 누락이나 여분 공백이 401의 전형적 원인입니다.
404: 경로 또는 모델
404 Not Found의 주된 원인은 두 가지입니다.
1. URL 경로 오류. 올바른 Chat Completions 엔드포인트는 /api/ai/v1/chat/completions입니다. 흔한 실수:
/api/ai/v1계층 누락(https://exaiv.com또는/v1만)/v1이중 기입(/api/ai/v1/v1/chat/completions)
2. 모델 ID 오류. ID는 /models 카탈로그에 실재하는 것만 유효합니다. qwen3.8-flash-next나 Qwen/Qwen3.8-Flash-Next 같은 가중치 이름은 실패합니다.
429: 레이트 리밋
429 Too Many Requests는 "잠시 후 다시 시도하라"는 서비스의 명시적 신호입니다. 지수 백오프로 재시도합니다:
import time
import openai
client = openai.OpenAI(api_key="YOUR_API_KEY", base_url="https://exaiv.com/api/ai/v1")
def call_with_retry(messages):
for attempt in range(4):
try:
return client.chat.completions.create(model="kimi-k3", messages=messages)
except openai.RateLimitError:
time.sleep(2 ** attempt) # 2, 4, 8초
raise RuntimeError("4회 재시도 후에도 레이트 리밋")
429는 서비스 중단이 아닙니다
429는 "바쁘다"는 능동적 응답이며 백오프로 대부분 해소됩니다. 재시도 없이 즉시 실패 처리하지 마세요. 반면 지속적으로 429가 나오면 병행 수량 사양 조정이 필요합니다.
503과 타임아웃
503: 일시적 서비스 불가. 횟수를 제한(3~4회)해 짧은 백오프로 재시도하고, 그래도 안 되면 폴백 또는 실패 종료. 무제한 재시도는 상황을 악화시킵니다.
타임아웃: HTTP 상태가 아니라 클라이언트가 정해진 시간 내 완전한 응답을 못 받은 상태. 확인 순:
--max-time 30붙인 curl도 타임아웃되는가 — 되면 네트워크 경로 문제- 요청이 너무 큰가 — 긴 컨텍스트, 큰
max_tokens를 줄여 재시도 - 프록시나 VPN이 경로에 없는가
모델 미발견과 카탈로그의 관계
"모델이 없다"는 말을 들으면 코드가 아니라 카탈로그를 먼저 확인합니다. Qwen 계열을 포함한 클라우드 제공 ID는 상류 업데이트에 맞춰 변동합니다. /models 실시간 목록에 없는 ID는 아무리 이름이 그럴듯해도 호출되지 않습니다. HuggingFace 오픈 가중치 이름은 API ID가 아닙니다 — 이 혼동이 가장 흔한 원인입니다.
가중치 이름을 API ID로 쓰지 마세요
Qwen/Qwen3.8-Flash-Next는 HuggingFace 가중치 이름이지 API ID가 아닙니다. API ID는 플랫폼 카탈로그가 공개한 문자열뿐입니다. 섞어 쓰지 마세요.
진단 순서 요약
| 단계 | 확인 | 대응 |
|---|---|---|
| 1 | Key | 재생성, 공백 제거 |
| 2 | URL | /api/ai/v1/chat/completions까지 과부족 없이 |
| 3 | 모델 ID | /models의 실재 ID로 수정 |
| 4 | 서비스 상태 | 횟수 제한 재시도, 폴백 |
| 5 | 네트워크 | curl로 확인, 요청 축소 |
FAQ
401은 항상 Key 문제인가요?
404는 URL과 모델 중 어느 쪽인가요?
429 재시도는 몇 회가 적절한가요?
타임아웃과 429의 차이는?
모델 ID는 어디서 확인하나요?
가격은 어디서 보나요?
관련 글
- Qwen 모델 선택 가이드 — 가족 사용 구분
- Kimi K3 vs GLM-5.3 비교 — 클라우드 쌍두 모델
- 로컬 배포 완전 플레이북 — 로컬 엔드포인트 구축
- 모델 카탈로그 — 현재 사용 가능한 ID