Kimi API 주요 오류와 속도 제한 해결: 401, 404, 429, 타임아웃 (2026)

Kimi API 오류는 먼저 세 가지를 봐야 합니다. HTTP 상태 코드, error.type, request_id입니다. 같은 429라도 서버 과부하, 조직 속도 제한, 잔액 부족일 수 있고, 같은 401이라도 키 오기나 중국 사이트·국제 사이트 혼용일 수 있습니다. 먼저 분류하고 나서 코드를 고치십시오.

이 글은 401, 404, 429, 타임아웃 네 가지로 나누어 원인, 진단 절차, 재사용 가능한 백오프 코드를 제시합니다. 모델과 가격은 사이트 내 모델 가격을 기준으로 합니다.

안내: Moonshot, Kimi는 해당 권리자의 상표입니다. 오류 유형, 속도 제한 규칙, 인터페이스 동작은 변경될 수 있습니다. 이 글은 2026년 10월의 일반적인 상황을 예로 들며, 최종적으로는 공식 문서를 기준으로 합니다.

1. 상태 코드 빠른 조회

상태 코드	오류 유형	일반적 의미	처리 방향
400	`invalid_request_error`	파라미터 오류, 컨텍스트 초과, 출력 상한 초과	요청 수정
400	`content_filter`	입력 또는 출력이 콘텐츠 안전 정책에 걸림	프롬프트 조정
401	`invalid_authentication_error`	키 무효, 지역 불일치	자격 증명 수정
401	`incorrect_api_key_error`	키 누락 또는 오류	자격 증명 수정
403	`permission_denied_error`	인터페이스 미개방, IP 허용 목록, 잔액·권한 문제	권한과 잔액 확인
404	`resource_not_found_error`	모델명 또는 경로 오류	모델 목록 확인
429	`engine_overloaded_error`	서버 과부하	백오프 재시도
429	`rate_limit_reached_error`	동시성, RPM, TPM, TPD 초과	속도 저하 또는 할당량 증설
429	`exceeded_current_quota_error`	미납, 잔액 부족, 쿠폰 만료	충전
499	`client_closed_request`	클라이언트 또는 프록시가 조기 연결 종료	타임아웃과 스트리밍 확인
500	`server_error`	서버 내부 오류	백오프 재시도
503	`server_unavailable`	서비스 일시 불가	백오프 재시도
504	`Gateway Time-out`	긴 요청 대기 초과	스트리밍으로 전환

잔액 부족은 진입점에 따라 403 또는 429로 나타날 수 있으므로 상태 코드만으로 판단하지 말고 error.type을 기준으로 하십시오. 로그에는 최소한 시각, 상태 코드, 오류 유형, 모델명, request_id를 기록하고 전체 키와 민감 내용은 기록하지 마십시오.

2. 401: 지역을 먼저 보고 키를 확인합니다

중국 사이트 키에 국제 사이트 주소를 붙였는지, 또는 그 반대인지 확인합니다. 두 사이트의 계정, 잔액, 키는 완전히 독립적입니다.
오픈 플랫폼, Kimi Code, 멤버십 등 서로 다른 제품 라인의 키를 혼용했는지 확인합니다.
키 앞뒤에 공백, 줄바꿈, 불필요한 따옴표가 있는지 확인합니다.
환경 변수가 실제로 로드되었는지 확인합니다. 접두사만 출력해 보면 됩니다.
키가 삭제·교체되었거나 현재 프로젝트 권한이 없는지 확인합니다.
요청 헤더가 Authorization: Bearer <key>인지, 경로가 /v1/chat/completions인지 확인합니다.

export MOONSHOT_API_KEY="여기에-키"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "max_completion_tokens": 64,
    "messages": [{"role": "user", "content": "OK만 답하세요"}]
  }'

이 명령이 200을 반환하면 키, 지역, 모델명 세 가지가 모두 통과한 것입니다. 그래도 401이 나오면 이미 정상 동작이 확인된 다른 키로 다시 테스트해 키 자체의 문제인지 게이트웨이 설정 문제인지 구분하십시오.

3. 404: 모델명과 base_url에서 가장 자주 틀립니다

404가 반드시 모델 서비스 종료를 뜻하지는 않습니다. 흔한 원인은 네 가지입니다.

OpenAI SDK를 쓰면서 base_url을 설정하지 않아 요청이 기본 OpenAI 주소로 가고 모델이 없다는 응답을 받았습니다.
모델명 철자가 틀렸거나, 현재 계정에 접근 권한이 없는 모델을 사용했습니다.
경로에 /v1이 더 붙거나 빠졌거나, 채팅 인터페이스를 다른 경로로 작성했습니다.
중국 사이트와 국제 사이트의 모델명과 권한이 다릅니다.

먼저 같은 키로 모델 목록을 조회해 계정이 무엇을 볼 수 있는지 확인하십시오.

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

목록에 없는 모델은 추측해서 쓰지 마십시오. 모델 가용성은 계정의 실제 반환값과 사이트 내 모델 가격을 기준으로 합니다. 모델 목록은 반환되지만 채팅 인터페이스가 계속 404라면 경로에 /v1이 빠지지 않았는지, 클라이언트가 base_url과 전체 경로를 중복으로 붙이지 않았는지 확인하십시오.

4. 429: 세 가지 유형, 처리 방식이 다릅니다

`error.type`	의미	재시도 가능	처리
`engine_overloaded_error`	서버 과부하	가능	`Retry-After`에 따라 백오프, 동시성 축소
`rate_limit_reached_error`	조직 단위 동시성, RPM, TPM, TPD 초과	일부 가능	속도 저하, 키 분리, 등급 상향
`exceeded_current_quota_error`	미납, 잔액 부족, 쿠폰 만료	재시도 금지	충전 또는 청구 확인

TPD 초과는 보통 다음 날까지 기다리거나 할당량을 높이는 수밖에 없으며 계속 재시도해도 의미가 없습니다. 429로 중단된 요청은 보통 과금되지 않지만 재시도가 성공하면 정상 과금됩니다. 비용이 걱정되어 무한 재시도하지도 말고, 429를 봤다고 이미 결제되었다고 오해하지도 마십시오. OpenAI SDK는 기본적으로 자동 재시도하므로 429 한 번이 여러 요청으로 확대될 수 있습니다. 운영 환경에서는 max_retries를 명시적으로 설정하고 자체 백오프 로직을 사용하십시오.

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="여기에-키",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k2.6",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("잔액 또는 할당량 부족, 먼저 충전하세요")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype, "대기", round(wait, 1), "초")
            time.sleep(wait)
    raise RuntimeError("재시도 횟수를 모두 사용했습니다")

재시도는 일시적 오류에만 적합합니다. 이미 부작용이 발생한 업무는 멱등 키나 상태 확인으로 실행 여부를 먼저 확인한 뒤 재전송 여부를 결정하십시오.

5. 타임아웃과 504

긴 문서 생성, 긴 문서 분석, 코드 에이전트에서 타임아웃이 가장 자주 발생합니다. 처리 순서는 다음과 같습니다.

비스트리밍을 stream=True로 바꿔 연결이 계속 데이터를 반환하게 합니다.
연결 타임아웃과 읽기 타임아웃을 합리적으로 설정하고 SDK 기본값을 그대로 쓰지 않습니다.
회사 프록시, 게이트웨이, 로컬 라우팅 도구가 연결을 조기에 끊는지 확인합니다. 이런 경우 499로 나타날 수 있습니다.
max_completion_tokens로 한 번의 출력 길이를 통제하고 초장문 작업은 분할 처리합니다.
타임아웃마다 요청 ID와 소요 시간을 기록해 모델이 느린지, 네트워크가 느린지, 게이트웨이가 느린지 구분합니다.

stream = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "배포 점검 목록을 작성하세요"}],
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

스트리밍은 단가를 낮추지 않지만 "타임아웃까지 기다렸다가 재시도"하는 낭비를 크게 줄입니다. 연결 타임아웃은 짧게, 읽기 타임아웃은 최장 생성 시간에 맞춰 설정하십시오. 스트리밍에서는 비스트리밍의 읽기 타임아웃을 그대로 쓰지 마십시오. 정상 생성 중에 클라이언트가 스스로 연결을 끊을 수 있습니다.

6. 진단 순서 표

상태 코드, error.type, request_id, 모델명, 발생 시각을 기록합니다.
401, 403은 지역, 키, 제품 라인, 권한, 잔액을 확인합니다.
404는 base_url, 모델명, 계정 권한을 확인하고 모델 목록으로 검증합니다.
400은 컨텍스트 길이, 출력 상한, 파일 형식, 콘텐츠 안전을 확인합니다.
429는 error.type에 따라 과부하, 속도 제한, 미납의 세 가지로 나눠 처리합니다.
499, 504는 스트리밍, 타임아웃, 프록시, 연결 유지를 확인합니다.
500, 503은 백오프 재시도하고 지속되면 request_id를 첨부해 서비스 제공자에게 문의합니다.
장애가 끝날 때마다 모니터링과 경보를 보강해 사용자 피드백으로만 발견하지 않도록 합니다.

자주 묻는 질문

429와 503의 차이는 무엇인가요?

429는 서버 과부하일 수도 있고 계정 할당량이나 잔액 문제일 수도 있으므로 error.type을 먼저 봐야 합니다. 503은 서비스가 일시적으로 불가하다는 뜻이며 보통 백오프 후 재시도합니다. 둘 다 고정 간격으로 몰아서 재시도해서는 안 된다는 점이 같습니다.

충전 후에도 401이 나오면?

충전과 키가 같은 지역, 같은 제품 라인에 속하는지 먼저 확인하십시오. 새로 만든 키로 테스트해 기존 키 삭제나 환경 변수 캐시 문제를 배제하십시오.

컨텍스트 초과는 어떤 오류로 나타나나요?

보통 400 invalid_request_error이며 오류 메시지에 입력 토큰 초과가 언급됩니다. 입력을 줄이거나 이전 대화를 잘라내거나 컨텍스트가 더 큰 모델로 바꾸십시오.

SDK 자동 재시도를 켜야 하나요?

켤 수는 있지만 상한을 두어야 합니다. 기본 재시도는 429를 확대할 수 있으므로 운영 환경에서는 SDK 자동 재시도를 끄고 오류 유형별로 자체 지수 백오프와 경보를 구현하는 것을 권합니다.

게이트웨이 오류와 공식 오류를 어떻게 구분하나요?

같은 요청을 직접 연결과 게이트웨이에 각각 보내 상태 코드, error.type, request_id를 비교하십시오. 업스트림, 네트워크, 키, 게이트웨이 설정 중 어디가 원인인지 빠르게 판단할 수 있습니다.

다음 단계

먼저 ZSQH AI 게이트웨이에서 테스트 키를 만들고 401, 404, 429, 타임아웃을 각각 한 번씩 리허설한 뒤 운영 모니터링에 연결하십시오. 모델 가용성과 가격은 모델 가격을 기준으로 합니다.