DeepSeek API의 오류는 대략 네 가지로 나뉩니다. 인증, 경로와 모델명, 속도 제한, 타임아웃입니다. 올바른 진단 순서는 먼저 HTTP 상태 코드와 오류 유형을 보고, 다음으로 요청 ID와 최소 재현을 확인하고, 마지막에야 프롬프트를 고치거나 모델을 바꾸는 것입니다. 순서가 반대가 되면 설정 문제를 모델 능력 문제로 오해하기 쉽습니다.
이 글은 401, 404, 429, 타임아웃 네 가지로 나누어 원인, 진단 단계, 재사용 가능한 백오프 코드를 제시합니다. 모델과 가격은 사이트 내 모델 가격을 기준으로 합니다.
안내: DeepSeek는 해당 권리자의 상표입니다. 오류 유형, 속도 제한 기준, 인터페이스 동작은 버전에 따라 조정될 수 있습니다. 이 글은 2026년 10월의 일반적인 상황을 예로 들며 최종적으로는 공식 문서를 기준으로 합니다.
1. 네 가지 오류를 먼저 구분하기
| 상태 또는 현상 | 일반적인 의미 | 전형적인 원인 | 처리 순서 |
|---|---|---|---|
| 401 | 인증 실패 | Key 오류, Bearer 누락, Key 만료 | 자격 증명부터 수정 |
| 404 | 경로 또는 모델 없음 | Base URL 오류, 오래된 모델명, 경로 중복 연결 | 주소와 모델명 확인 |
| 429 | 속도 제한 또는 할당량 제한 | 동시성 급증, Key 공유, 재시도 폭풍 | 백오프, 동시성 축소 |
| 타임아웃 | 연결 또는 읽기 타임아웃 | 네트워크, 긴 출력, 추론 모델, 프록시 | 계층별 진단 |
| 400 | 요청 파라미터 또는 컨텍스트 문제 | 컨텍스트 초과, 형식 오류 | 계량 후 분할 |
| 5xx | 업스트림 서비스 오류 | 서버 장애 또는 과부하 | 백오프, 경로 전환 |
로그에는 최소한 시간, 상태 코드, 오류 유형, 모델명, 소요 시간, 요청 ID를 기록하십시오. 전체 Key를 기록하거나 사용자 원문을 통째로 로그에 출력하지 마십시오.
2. 401: 요청 헤더를 먼저, 그다음 Key
401은 신원이 검증되지 않았다는 뜻이며 모델 능력이나 잔액과는 대개 무관합니다. 다음 순서로 확인하십시오.
- 요청 헤더가 다른 인증 방식이 아니라
Authorization: Bearer <key>인지 확인합니다. - Key 앞뒤에 공백, 줄바꿈, 불필요한 따옴표가 있는지 봅니다. 채팅 창에서 복사할 때 가장 많이 섞여 들어갑니다.
- 환경 변수가 실제로 로드되었는지 확인하고, 접두사만 출력해도 됩니다.
- Key가 삭제, 교체 또는 비활성화되지 않았는지 확인합니다.
- Base URL과 Key가 같은 플랫폼에 속하는지 확인합니다. 공식 Key에 게이트웨이 주소를 쓰면 401이 발생합니다.
- 리버스 프록시가
Authorization헤더를 덮어쓰거나 버리지 않았는지 확인합니다.
export DEEPSEEK_API_KEY="sk-여기에_키"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "OK라고만 답하세요"}],
"max_tokens": 16
}'
이 명령이 200을 반환하면 Key, Base URL, 모델명 세 가지가 모두 통과한 것입니다. 그래도 401이라면 새 Key로 최소 요청을 실행해 Key 자체의 문제인지 프록시나 게이트웨이 설정 문제인지 구분하십시오.
3. 404: 주소와 모델명이 가장 자주 틀린다
404는 대개 "인터페이스가 죽었다"가 아니라 요청이 존재하지 않는 경로나 모델에 도달했다는 뜻입니다. 흔한 원인은 다음과 같습니다.
- Base URL을 다른 업체 주소로 쓰거나
/v1을 더 쓰거나 빼먹었습니다. - SDK가
/chat/completions를 자동으로 붙이는데 수동 경로에서 또 붙였습니다. - 이미 종료된 이전 버전 모델명을 쓰거나 대소문자, 접미사가 일치하지 않습니다.
- 게이트웨이 주소와 공식 주소를 섞어 쓰는데 경로 규칙이 다릅니다.
- 리버스 프록시의 재작성 규칙이 경로를 망가뜨렸습니다.
진단할 때는 먼저 curl로 전체 주소를 호출해 응답 본문의 오류 정보를 확인하고, Base URL과 모델명을 사이트 가격 페이지와 항목별로 대조하십시오. 코드에 여러 주소를 하드코딩하지 말고 환경별로 설정해 테스트 환경 주소가 운영으로 넘어가지 않게 하십시오.
4. 429: 속도 제한은 잔액 부족이 아니다
429는 요청이 속도, 동시성 또는 할당량 한도를 초과했다는 뜻입니다. DeepSeek는 피크 시간에 요청을 제한하거나 대기열에 넣을 수 있으며 구체적인 기준은 공식 문서를 따릅니다. 흔한 발생 상황은 다음과 같습니다.
- 여러 서비스가 Key 하나를 공유해 서로 할당량을 잡아먹습니다.
- 배치 작업이 정시에 동시에 시작되어 트래픽 급증을 만듭니다.
- 재시도에 백오프가 없어 실패할수록 더 많이 보내 재시도 폭풍이 됩니다.
- 긴 출력이나 추론 작업이 자원을 많이 차지해 동시성 여유가 줄어듭니다.
| 현상 | 가능한 원인 | 처리 |
|---|---|---|
| 피크 시간에 429 집중 | 업스트림 부하 또는 트래픽 급증 | 대기열, 분산 전송, 시간 분산 |
| 단일 Key 다중 서비스 429 | 할당량 공유 | 프로젝트별 Key 분리 |
| 재시도 후 더 악화 | 백오프 없는 재시도 | 지수 백오프와 무작위 지터 |
| 긴 요청이 먼저 429 | 출력 Token 점유가 높음 | max_tokens 또는 동시성 축소 |
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError
client = OpenAI(
api_key="sk-여기에_키",
base_url="https://api.deepseek.com",
max_retries=0, # SDK 자동 재시도를 꺼서 사용자 정의 재시도와 겹치지 않게 함
)
def ask(prompt: str, retries: int = 4) -> str:
for attempt in range(retries):
try:
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": prompt}],
max_tokens=1024,
timeout=60,
)
return resp.choices[0].message.content
except (RateLimitError, APITimeoutError):
wait = min(2 ** attempt, 20) + random.random()
print(f"{attempt + 1}번째 실패, {wait:.1f}초 대기")
time.sleep(wait)
except APIStatusError as exc:
if exc.status_code >= 500:
wait = min(2 ** attempt, 20) + random.random()
time.sleep(wait)
continue
raise
raise RuntimeError("재시도 횟수를 모두 사용했습니다")
print(ask("속도 제한이 무엇인지 한 문장으로 설명하세요"))
재시도는 일시적 오류에만 적합합니다. 이미 부작용이 발생한 업무는 멱등 키나 상태 확인으로 실행 여부를 먼저 확인한 뒤 다시 보낼지 결정하십시오.
5. 타임아웃: 연결, 읽기, 스트리밍을 먼저 구분하기
타임아웃은 서비스 불가와 같지 않으므로 어느 구간에서 멈췄는지 먼저 찾아야 합니다.
| 현상 | 가능한 원인 | 처리 |
|---|---|---|
| 연결 타임아웃 | DNS, 네트워크 출구, 프록시 도달 불가 | 네트워크와 프록시 확인, 회선 변경 |
| 첫 Token이 매우 느림 | 업스트림 대기, 프롬프트 과다 | 입력 축소, 시간 분산, 경량 모델 전환 |
| 읽기 타임아웃 | 출력이 너무 길거나 추론 모델이 오래 생각 | 읽기 타임아웃 상향, 출력 제한 |
| 스트리밍 중단 | 네트워크 흔들림, 프록시 단절 | 재연결 지원, 수신 내용 기록 |
| 전체 동시 타임아웃 | 로컬 출구 또는 업스트림 장애 | 대체 경로 전환, 서비스 상태 확인 |
import httpx
from openai import OpenAI
client = OpenAI(
api_key="sk-여기에_키",
base_url="https://api.deepseek.com",
timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)
연결 타임아웃과 읽기 타임아웃은 따로 설정해야 합니다. 모든 타임아웃을 매우 큰 값으로 두면 장애 시 스레드 풀이 묶이고, 너무 작게 두면 정상적인 긴 작업을 잘못 중단시킵니다. 작업 유형별로 따로 구성하는 편이 안전합니다.
6. 진단 순서 표
- 상태 코드, 오류 유형, 요청 ID, 모델명, 발생 시간을 기록합니다.
- 401은 Key, 요청 헤더, 환경 변수, 플랫폼 일치 여부를 확인합니다.
- 404는 Base URL, 경로 연결, 모델명을 확인합니다.
- 400은 파라미터, 컨텍스트 길이, 이미지 또는 파일 형식을 확인합니다.
- 429는 동시성, Key 공유, 재시도 정책, 피크 시간대를 확인합니다.
- 타임아웃은 DNS, 프록시, 출력 길이, 읽기 타임아웃 설정을 확인합니다.
- 5xx는 먼저 백오프 재시도하고 지속되면 요청 ID를 첨부해 서비스 제공자에게 문의합니다.
- 장애가 끝날 때마다 모니터링과 경고를 보강하고 사용자 피드백을 기다리지 마십시오.
7. 모니터링과 로그
| 필드 | 용도 |
|---|---|
| 시간과 프로젝트 | 피크와 영향 범위 파악 |
| 상태 코드와 오류 유형 | 인증, 속도 제한, 업스트림 오류 구분 |
| 요청 ID | 서비스 제공자에게 문의할 때 핵심 증거 |
| 모델명과 버전 | 모델 교체 후 발생했는지 판단 |
| 입력 및 출력 Token | 비용과 긴 요청 분석 |
| 소요 시간과 재시도 횟수 | 꼬리 지연과 재시도 폭풍 발견 |
모니터링은 최소한 시간 단위로 401, 404, 429, 타임아웃, 5xx 건수를 집계해야 합니다. 오류율이 급증하면 특정 프로젝트, Key, 모델에 집중되는지 먼저 보고 동시성 축소, 경로 전환, 버전 롤백 중 무엇을 할지 결정하십시오.
자주 묻는 질문
429는 잔액 부족인가요?
아닙니다. 429는 요청이 속도, 동시성 또는 할당량 한도를 초과했다는 뜻이며 잔액 부족은 보통 다른 오류를 반환하거나 응답 본문에 설명됩니다. 동시성과 Key 공유를 먼저 확인하고 그다음 계정 잔액을 확인하십시오.
404의 가장 흔한 원인은 무엇인가요?
Base URL 오류, 경로 중복 연결, 모델명 만료입니다. 먼저 curl로 전체 주소를 호출하고 사이트 가격 페이지와 모델명을 대조하면 대개 몇 분 안에 찾을 수 있습니다.
타임아웃에 무한 재시도를 해야 하나요?
아닙니다. 재시도에는 상한, 백오프, 경고가 필요합니다. 타임아웃은 요청이 이미 업스트림에서 실행되었을 수도 있다는 뜻입니다. 부작용이 있는 업무는 상태를 먼저 확인한 뒤 재전송 여부를 결정하십시오.
스트리밍 출력이 중단되면 어떻게 하나요?
수신한 내용과 중단 위치를 먼저 기록하고 네트워크 흔들림, 프록시 단절, 업스트림 타임아웃 중 무엇인지 판단합니다. 클라이언트는 재연결과 중복 제거를 지원해야 하며 잘린 내용을 완전한 결과로 저장하지 마십시오.
게이트웨이 오류와 공식 오류를 어떻게 구분하나요?
요청 ID와 오류 유형을 보관하고 같은 요청을 공식 진입점과 게이트웨이 진입점에 각각 보내십시오. Key, 네트워크, 게이트웨이 설정, 업스트림 서비스 중 어디에 문제가 있는지 빠르게 구분할 수 있습니다.
다음 단계
먼저 ZSQH AI Gateway에서 테스트 Key를 만들고 401, 404, 429, 타임아웃을 각각 한 번씩 연습한 뒤 운영 모니터링에 연결하십시오. 모델 가용성과 가격은 모델 가격을 기준으로 합니다.
관련 읽을거리:
