DeepSeek API 호출 실패 시 오류를 진단하고 대체 모델로 전환하는 방법

DeepSeek API 요청이 실패하면 먼저 어느 엔드포인트가 응답했는지, 무엇이 실패했는지, 작업이 이미 완료되었을 가능성이 있는지 확인해야 합니다. 인증, 잔액, 요청 형식 오류는 재시도 전에 해결하세요. 일시적인 호출 제한이나 서버 오류에는 횟수를 제한한 재시도 정책을 적용하고, 그래도 실패하면 접근 권한·작업 호환성·데이터 처리 정책을 사전에 승인한 대체 경로로만 전환하세요.

이 글은 애플리케이션이나 코딩 작업에 DeepSeek를 사용하는 개발자를 위한 안내입니다. 진단용 요청, 오류별 대응 표, Ofox 카탈로그의 구체적인 대체 후보, 다운로드 가능한 Python 전환 예제를 제공합니다. 예제는 스트리밍을 사용하지 않는 짧은 텍스트 작업을 처리합니다. 에이전트 세션을 자동으로 이전하거나 도구를 실행하지는 않습니다.

검증 기준일: 2026년 10월 19일. 공개 문서와 Ofox 카탈로그를 확인했으며, 로컬 합성 테스트 14개를 통과했습니다. 유료 모델 추론을 실행하거나 상위 서비스의 장애를 재현하지는 않았습니다. 카탈로그 등재만으로 해당 계정에서 호출할 수 있다거나, 출력 품질이 요구 사항에 맞거나, 다음 장애에서도 작동한다고 볼 수는 없습니다. 이 글의 발행자인 Ofox는 본문에서 다루는 게이트웨이 선택지 중 하나입니다.

1. 로컬 환경, 계정, 상위 서비스 중 어디에서 실패했는지 확인하기

DeepSeek 상태 페이지와 실제로 사용하는 게이트웨이의 상태 정보부터 확인하세요. 정상 표시가 참고는 되지만, 현재 사용하는 경로까지 정상임을 입증하지는 않습니다. 특정 지역의 장애, 막 발생한 문제, 계정별 오류는 아직 표시되지 않았을 수 있습니다.

설정을 바꾸기 전에 간단한 장애 기록을 남기세요.

예를 들어 같은 프롬프트가 애플리케이션에서는 실패하지만 최소 요청에서는 성공한다면, 요청 본문·SDK·프록시·타임아웃 설정을 우선 살펴볼 수 있습니다. 한 모델만 실패하고 다른 모델은 응답한다면 조사 범위를 좁힐 수 있지만, 게이트웨이 전체가 정상이라는 뜻은 아닙니다. 모델마다 어댑터와 상위 서비스 경로가 다를 수 있기 때문입니다.

조사 중에는 예약 작업이 계속 새 요청을 쌓지 않도록 멈추세요. 큐가 늘어나면서 재시도까지 반복되면 짧은 장애가 긴 복구 작업으로 이어질 수 있습니다. 복구 과정에서 모든 작업이 두 번 생성되지 않도록 원래 작업 ID를 유지하세요.

2. 오류 유형에 맞는 조치 선택하기

2026년 10월 19일에 캡처한 공식 영문 문서입니다. 실패한 API 호출 화면이 아니라 오류 참고 문서의 스크린샷입니다.

아래 표의 첫 일곱 유형은 DeepSeek의 공식 오류 문서를 따릅니다. 게이트웨이는 자체 오류 코드를 추가하거나 상위 서비스 응답을 변환할 수 있으므로 HTTP 상태와 문서에 정의된 오류 본문을 함께 확인하세요.

429가 항상 기다리면 해결되는 것은 아닙니다. 일부 제공자는 크레딧 소진이나 고정 할당량 초과에도 이 코드를 사용합니다. 예제는 인식 가능한 할당량 오류 코드에서 중단합니다. 운영에 적용하기 전에는 제공자의 공식 오류 구조에 맞춰 분류를 확장하세요. 마찬가지로 타임아웃은 클라이언트가 관측한 현상이지, 토큰이 전혀 소비되지 않았다는 증거가 아닙니다.

DeepSeek는 호출 제한 안내에서 계정 단위 동시 요청 제한과 과부하 요청의 별도 처리 방식을 설명합니다. 같은 계정을 공유하는 모든 워커와 API 키의 진행 중 요청을 합산하세요. 워커 하나만 느리게 동작하도록 바꿔도 계정 전체는 여전히 한도를 초과할 수 있습니다.

3. 작은 진단 요청 한 번 실행하기

DeepSeek 직접 접속 서비스에서 현재 문서에 명시된 Flash ID는 deepseek-flash입니다. 게이트웨이에서도 같은 ID를 사용한다고 가정해서는 안 됩니다. 현재 매핑은 공식 API 소개에서 확인할 수 있습니다. 처음 연결한다면 DeepSeek API 설정 안내를 참고하세요.

명령 추적이 꺼진 신뢰할 수 있는 셸, 기존 비밀 저장소에서 가져온 환경 변수, 빈 작업 디렉터리를 사용하세요. 다음 요청은 합성 문구만 전송하며 일반 추론 요금이 발생할 수 있습니다. 과부하 상태인 서비스에 반복해서 실행하지 마세요.

umask 077
curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 45 \
  --dump-header response-headers.txt \
  --output response-body.json \
  --write-out 'HTTP %{http_code}; total %{time_total}s\n' \
  https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with exactly: DIAGNOSTIC_OK"}],"stream":false,"max_tokens":128,"thinking":{"type":"disabled"}}'

연결 5초, 전체 45초는 이 진단을 위해 선택한 제한이며 DeepSeek의 서비스 보장 수치가 아닙니다. 긴 추론 작업에는 다른 제한 시간이 필요할 수 있습니다. --fail-with-body는 해당 옵션을 지원하는 curl 버전에서만 작동하므로, 옵션 오류가 나면 curl --version으로 확인하세요. 상세 추적을 켜거나 실제 키를 넣은 명령을 지원 문의에 붙여 넣지 마세요. 로컬 프로세스 조회에서도 확장된 명령 인수가 노출될 수 있으므로, 공유 환경에서는 비밀 관리자와 연동한 SDK를 사용하세요.

유효한 진단 결과는 HTTP 200, DIAGNOSTIC_OK가 포함된 비어 있지 않은 완전한 답변, 그리고 반환된 경우 기록된 사용량입니다. choices[0].finish_reason도 확인하세요. 길이 제한으로 끝난 출력은 정상적으로 완료된 답변과 같은 조건을 충족하지 않습니다. 실패했다면 민감 정보를 제거한 오류 내용을 보관하세요. 위 두 파일은 다음 실행에서 덮어쓸 수 있으므로 시도별 비교에는 별도 디렉터리를 사용하세요.

진단 요청이 성공하면 실제 요청의 기능을 하나씩 복원하세요. 긴 대화 기록, 추론, 구조화 출력, 도구, 스트리밍 순으로 추가하면 어느 단계부터 실패하는지 확인할 수 있습니다. 단순히 연결을 진단하려고 운영 중인 대화를 새로운 제공자에게 보내지는 마세요.

4. 어떤 대체 경로가 실제로 도움이 되는지 판단하기

흔히 ‘폴백’이라고 부르는 변경에는 세 가지가 있습니다.

같은 제공자 계정의 키 두 개는 할당량을 공유할 수 있습니다. 서로 다른 모델 이름이 같은 배포를 가리킬 수도 있고, 두 게이트웨이가 같은 상위 서비스를 호출할 수도 있습니다. 공개된 경우 실제 서빙 제공자를 기록하고, 라우팅이 불투명하면 확인을 요청하세요. URL이 다르다는 사실만으로 독립성을 검증할 수는 없습니다.

단순 요약이나 추출이라면 별도로 검증한 텍스트 모델을 제한적인 대체 운영에 사용할 수 있습니다. 코드 변경은 결과물에 프로젝트 테스트를 실행하세요. 이미지 이해는 실제 이미지 입력 경로를 검증하세요. 도구를 사용하는 에이전트는 시스템 지침, 완료된 도구 결과, 대기 중인 작업 상태를 보존해야 합니다. 제공자별 추론 블록을 다른 프로토콜로 무작정 복사하지 마세요.

개인정보 또는 계약상 제약 때문에 대체 제공자에게 데이터를 보낼 수 없다면 작업을 큐에 보관하거나 일시적으로 사용할 수 없다는 명확한 응답을 반환하세요. 가용성을 높이기 위해 승인된 데이터 처리 범위를 넘어서는 안 됩니다.

5. 정확한 모델 ID로 Ofox 대체 경로 준비하기

10월 19일 Ofox의 공개 모델 카탈로그에서 다음 항목을 확인했습니다. 이는 카탈로그 확인 결과이며, 추론 호출 성공 테스트나 특정 모델의 우수성을 입증하는 추천은 아닙니다.

카탈로그는 이 항목들에 OpenAI Chat Completions를 표시합니다. 두 DeepSeek 항목에서는 내장 web_search와 web_fetch가 별도로 false로 표시되어 있습니다. DeepSeek 직접 서비스의 Search/Fetch 기능이나 과금 규칙이 Ofox 모델 ID에도 그대로 적용된다고 가정하지 마세요. 이 글의 전환 예제는 제공자 고유 검색이 아닌 텍스트 Chat Completions만 사용합니다.

경로는 다음 순서로 준비하세요.

1. 현재 카탈로그 항목, 지원 프로토콜, 계정에 적용되는 요금을 확인하세요. 이 글은 Ofox 가격을 제시하거나 무료 사용을 약속하지 않습니다.
2. 요구 사항에 맞으면 Ofox 계정을 만들고 API Keys에서 키를 생성하세요. 인증 문서를 따르세요. Ofox 키와 DeepSeek 직접 접속용 키는 서로 다른 계정에 속합니다.
3. OpenAI 호환 경로의 SDK 기본 URL은 https://api.ofox.io/v1입니다. 원시 HTTP 요청에서는 /chat/completions를 한 번만 추가하세요. /v1/v1이 되거나 이 경로에 Anthropic 메시지 형식의 본문을 보내지 않도록 주의하세요.
4. 후보의 정확한 모델 ID를 복사하고 민감 정보가 없는 진단 요청을 보낸 뒤, 반환된 내용·사용량·요청 기록을 확인하세요. 필요한 충전은 계정 조건을 확인한 후 별도로 진행하세요.
5. 아래의 대표 작업 및 비용 검증을 통과한 뒤에만 운영용 대체 경로로 추가하세요.

기본 경로와 대체 경로가 모두 Ofox를 사용한다면 Ofox 게이트웨이는 공통 의존성으로 남습니다. 게이트웨이 장애에도 대비해야 한다면 그 게이트웨이 밖의 경로를 승인하세요. 이 후보들의 운영상 독립성이나 가동률 보장은 검증하지 않았습니다.

6. 재시도 제한과 전환 동작을 로컬에서 테스트하기

Python 예제와 테스트 다운로드. 패키지에는 failover.py, test_failover.py, README가 들어 있습니다. 새 디렉터리에 압축을 풀고 다음 명령을 실행하세요.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m unittest -v

10월 19일 실행에서는 주입된 응답과 합성 인증 정보를 사용한 테스트 메서드 14개가 통과했습니다. 이 테스트는 네트워크를 호출하지 않습니다. 기본 경로 성공, 503 이후 복구, 두 번 실패한 뒤 대체 경로 사용, 재시도를 중단해야 하는 HTTP 오류, 할당량 소진과 일시적 제한에 따른 429 구분, 시도 횟수 소진, 완료 여부가 불명확한 전송 오류, 명시적 재전송 허용, TLS 실패, 잘못된 성공 응답, 숫자·날짜 형식의 Retry-After 처리를 검증합니다.

제어기는 기본 경로 최대 두 번, 대체 경로 최대 한 번만 시도합니다. 재시도하거나 경로를 바꾸기 전에 Retry-After를 따릅니다. 대기 시간이 예제의 30초 대기 예산을 넘으면 호출자가 작업을 큐에 넣을 수 있도록 중단합니다. 유효한 헤더가 없으면 상한이 있는 무작위 지연을 적용합니다. 목적지가 의도치 않게 바뀌지 않도록 리디렉션은 비활성화했습니다. 각 경로는 별도의 키와 모델을 사용합니다.

실제 요청을 보내려면 승인된 비밀 관리자를 통해 다음 환경 변수를 설정하세요.

DEEPSEEK_API_KEY = your direct DeepSeek key
BACKUP_BASE_URL  = https://api.ofox.io/v1
BACKUP_MODEL     = deepseek/deepseek-v4.1-flash-1017
BACKUP_API_KEY   = your Ofox key
BACKUP_DISABLE_THINKING = 1

위 DeepSeek 대체 모델에서는 짧은 진단 답변을 위해 BACKUP_DISABLE_THINKING=1로 추론을 명시적으로 끕니다. 다른 모델 계열을 선택한다면 이 플래그를 제거하고 해당 모델의 공식 설정과 충분한 출력 예산을 사용하세요. DeepSeek 전용 매개변수를 자동 전달하지 마세요. 이 매개변수 구성도 실제 경로에서 별도로 확인해야 합니다.

이후 python failover.py를 실행하세요. 고정된 텍스트 프롬프트를 보내므로 요금이 발생할 수 있습니다. 선택한 경로, 요청·반환 모델, 텍스트, 사용량, 제공되는 경우 요청 ID를 출력합니다. 예상 답변은 FALLBACK_TEST_OK이며, 정확히 이 문자열인지 직접 확인해야 합니다. 기본 경로가 정상적으로 성공하면 실제 대체 경로는 호출되지 않습니다. 대체 경로 자체를 검증하려면 문서에 명시된 해당 경로로 진단 요청을 직접 보내세요. 기본 서비스를 일부러 과부하 상태로 만들거나 고장 내지 마세요.

전송 오류에서는 서버가 이미 요청을 수락했을 수 있으므로 기본적으로 중단합니다. python failover.py --allow-ambiguous-replay는 외부 상태를 변경하지 않는 이 고정 텍스트 작업에 한해 다음 시도를 명시적으로 허용합니다. 도구 작업, 결제, 이메일 발송, 파일 변경을 재실행해도 된다는 뜻이 아닙니다. 단순 생성이라도 두 번 과금될 수 있습니다.

예제는 SDK의 숨겨진 상태 코드 재시도 없이 Requests를 직접 사용합니다. SDK에 이 정책을 통합한다면 SDK 재시도를 끄거나 같은 시도 예산 안에 포함하세요. 연결 5초, 읽기 비활성 시간 30초의 타임아웃은 전체 실행 시간을 제한하는 기한이 아닙니다. 운영 코드에는 전체 제한 시간, 공유 동시성 제어, 영속적인 회로 차단 상태, 작업별 출력 검증도 필요합니다.

7. 스트리밍과 도구 실행은 별도로 복구하기

출력이 이미 사용자에게 전달되었다면 그 뒤에 다른 모델의 답변 첫 부분을 이어 붙이지 마세요. 첫 응답을 중단 상태로 표시하세요. 사용자나 애플리케이션이 생성을 다시 시작하면 새 답변을 분리하고 두 시도를 모두 기록하세요. 연결에서 하트비트나 공백을 받았다고 유용한 출력이 도착한 것은 아닐 수 있습니다. 연결 활동과 함께 의미 있는 내용이 도착하기까지의 시간도 측정하세요.

도구 호출 생성과 실제 실행은 별개 단계입니다. 모델이 도구 호출을 반환했다고 작업이 실행된 것은 아니며, 실행기가 작업을 수행한 뒤 네트워크가 끊겼다고 작업이 실패한 것도 아닙니다. 작업 ID, 동작 인수 또는 안전한 참조, 실행 상태, 결과를 담은 영속적인 작업 원장을 유지하세요. 재개하기 전에 결과가 불명확한 동작을 확인해야 합니다. 후속 서비스가 멱등성을 지원하면 활용하되, 임의의 멱등성 헤더를 만들고 제공자가 이를 처리한다고 가정하지 마세요.

실제 복구 순서는 새 동작 전송 중단, 완료된 동작 식별, 저장된 결과 복원, 대기 중인 동작 검증, 승인된 모델로 재개의 흐름입니다. 상태를 안전하게 확인할 수 없다면 검토를 위해 중단하세요. 다운로드 예제에는 의도적으로 도구 실행기와 스트리밍 파서를 포함하지 않았습니다.

8. 대체 모델을 검증하고 비용을 확인한 뒤 기본 경로로 복귀하기

장애 전에 대표 사례를 준비하세요. 일반적인 작업, 길지만 지원 범위 안에 있는 입력, 필요한 경우 구조화 출력 작업, 그리고 필수 도구·이미지 작업 각각이 포함되어야 합니다. 사례별 정확성 기준도 정하세요. 유효한 JSON 객체에도 잘못된 값이 들어갈 수 있고, 컴파일되는 코드도 요구한 동작에는 실패할 수 있습니다.

경로, 요청한 정확한 모델, 제공되는 경우 반환 모델, 입력 크기, 매개변수, 지연 시간, 종료 사유, 사용량, 청구 기록, 합격·불합격 결과를 기록하세요. 사용량이 없으면 비용을 모르는 것이지 비용이 0이라는 뜻은 아닙니다. 기본 경로에서 캐시된 프롬프트가 대체 경로에서도 캐시에 적중한다고 볼 수 없습니다. 청구 내역을 대조할 때 실패 및 재시도한 요청도 포함하세요.

제한 운영 정책을 정하세요. 어떤 작업에 대체 모델을 허용할지, 허용 비용과 최대 시도 횟수는 얼마인지, 실패 후 어떻게 처리할지가 필요합니다. 단순 내부 요약은 문체가 달라도 괜찮을 수 있지만, 금융 정보 추출이나 파괴적인 코드 작업은 검토가 필요할 수 있습니다. 대체 모델이 더 빨리 응답한다는 이유만으로 알리지 않고 전환하지 마세요.

실패가 지속되면 해당 경로의 회로 차단기를 열어 일반 트래픽 전송을 멈추세요. 냉각 기간 후 소량의 점검 요청을 허용하고, 대표 검증이 연속으로 성공한 뒤 트래픽을 점진적으로 복원하세요. 임계값은 블로그에 나온 보편적인 숫자가 아니라 애플리케이션의 제한 시간과 위험도에 맞춰 정해야 합니다. 개별 실패가 발생할 때마다 경로 사이를 오가지 마세요. 복구 후에도 대체 설정을 유지하고 장애 시간표를 남기세요.

추가 지원이 필요하면 시각, 민감 정보를 제거한 상태·오류 코드, 요청 모델, 클라이언트 버전, 요청 ID, 최소 합성 재현 사례를 보내세요. 키, 비공개 프롬프트, 고객 파일은 제외하세요. 클라이언트별 문제를 더 조사하려면 DeepSeek 클라이언트 간 결과 차이 진단 안내를, 일반적인 상태 코드 의미는 API 오류 코드 참고 문서(영문)를 확인하세요.

최종 검증 목표는 구체적이어야 합니다. 실패 원인 하나를 정확히 진단하고, 재시도 상한을 테스트하며, 승인된 대체 경로가 실제 작업을 완료하고, 복구 과정에서 동작을 중복 실행하지 않아야 합니다. 카탈로그 등재와 성공 HTTP 응답은 그 결과에 도달하기 위한 일부 단계일 뿐입니다.