Kimi Troubleshooting

상위 문서: ← Kimi Debugging and operations 출처: Kimi API Platform 공식 문서 — Troubleshooting 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

Kimi API를 사용하면서 마주칠 수 있는 자주 묻는 문제와 해결책을 모았습니다. 아래는 자주 보고되는 케이스만 정리한 요약입니다. 전체 FAQ는 공식 Troubleshooting 문서를 참고하세요.

1. 잔액/Key 공유 여부

Kimi API Open Platform, Kimi Code, Kimi Membership은 독립적인 제품입니다. 각자의 과금 모델, 잔액, API Key는 호환되지 않습니다.

Kimi API Open Platform — 종량제, 구독 플랜 없음. Open Platform 콘솔에서 API Key를 만들어 사용
Kimi Code — 별도의 코딩 제품. Open Platform Key와 호환되지 않음
Kimi Membership (구독) — Open Platform 잔액과 교환 불가

다른 제품의 Key로 Open Platform 엔드포인트를 호출하면 401 또는 404. 아래 401/404 체크리스트 참조.

2. 충전 후에도 429 발생

429는 단일 원인이 아닙니다. 먼저 응답의 error.type을 확인:

engine_overloaded_error — 서비스 노드 과부하(피크 시간 용량 압박). Retry-After만큼 대기, 동시성 줄이고 exponential backoff. 충전/등급 업그레이드로 해결되지 않음
rate_limit_reached_error — 조직 동시성, RPM, TPM, TPD 한도 도달. 요청 빈도 줄이거나 Top-up and Rate Limits에서 등급 업그레이드
exceeded_current_quota_error — 잔액 부족, 연체, 바우처 만료. balance API로 available_balance 확인 후 충전

OpenAI SDK는 기본 재시도를 포함하므로 단일 작업이 여러 요청으로 증폭될 수 있어 rate-limit 할당량을 빠르게 소진할 수 있습니다. 실제 요청 수와 클라이언트 로그를 함께 확인하세요.

429로 중단된 요청은 과금되지 않습니다.

3. 401 / 404 / permission denied 체크리스트

다른 제품의 Key를 쓰고 있지 않은지 (Open Platform ↔ Kimi Code)
Key 발급 지역과 엔드포인트 일치 여부 (accounts/balances/keys는 지역별 격리)
계정에 사용 가능 잔액이 있는지, 대상 모델을 커버하는 바우처인지
같은 Key로 GET /v1/models 호출해 대상 모델이 반환 목록에 있는지 확인
모델명 매칭 — 직접 API / Codex는 kimi-k3, Claude Code는 호환 alias kimi-k3[1m]. 해당 통합 튜토리얼 따르기
로컬 라우팅 도구(CC Switch 등)의 환경 변수/프록시/이전 설정 잔여물 정리

추가: Error Codes, Claude Code 통합, Codex 통합.

4. 서드파티 에이전트/IDE 설정 후 실패

두 계층으로 분리: Kimi API / 서드파티 도구.

같은 Key·엔드포인트·모델로 Kimi API를 직접 호출 (cURL 예제는 K3 quickstart)
직접 호출이 실패하면 잔액/인증/모델 권한/요청 파라미터부터 해결
직접 호출은 성공하지만 도구만 실패하면 도구 로그 확인 — 프로토콜 변환, 스트리밍 응답, 타임아웃, 자동 재시도
Claude Code, Codex, OpenCode 등 도구별 튜토리얼 따르기 — 모델명/설정이 다를 수 있음
클라이언트 버전, 발생 시각, request_id, 실제 요청 엔드포인트, 마스킹된 로그 보관

CC Switch, Trae 같은 서드파티 도구는 Kimi Open Platform이 유지하지 않습니다. 직접 API 호출은 성공하지만 도구만 실패하면 해당 도구 지원 채널에도 연락.

5. 에이전트에 결과 없는데 과금됨

클라이언트에 결과가 없다고 API 요청이 실패한 것은 아닙니다. 코딩 도구가 너무 일찍 대기를 중단하거나, 프록시가 끊기거나, 로컬 타임아웃이 발생하면 서버 측 요청은 정상 완료되어 실제 호출 기록이 생깁니다.

확인 순서:

요청의 HTTP 상태 코드 / request_id
API 응답의 usage 필드
클라이언트가 자동 재시도/서브 에이전트 생성/도구 호출 루프를 했는지
콘솔의 사용량 대시보드·과금 내역
클라이언트 로그의 타임아웃·연결 오류

플랫폼 기록과 클라이언트 기록이 명확히 불일치하면 api-service@moonshot.ai에 organization ID, 프로젝트, 발생 시각, request_id, 모델, 클라이언트 버전, 마스킹 로그, 과금 내역을 첨부해 메일.

6. 과금 내역 검토 & 예상치 못한 과금 신고

Open Platform 콘솔에서 사용량 대시보드·과금 내역 검토 → 시간·프로젝트·모델·request_id로 클라이언트 로그/API의 usage와 대조.

플랫폼팀 도움이 필요하면 organization ID, 프로젝트명, 발생 시각(시간대 포함), request_id, 모델명, 클라이언트·버전, 마스킹 로그, 과금/내보내기 기록을 준비해 api-service@moonshot.ai로 메일.

7. Context Caching 수동 설정?

불필요 — Kimi API가 반복되는 초기 컨텍스트를 자동으로 캐시 시도. cache ID, TTL, 추가 요청 파라미터 불필요.

초기 prefix(system prompt, 도구 정의, 긴 문서)를 안정적으로 유지하면 후속 요청의 캐시 적중률이 올라갑니다. prefix를 수정하면 적중률이 떨어질 수 있음. 자세한 내용: Context Caching.

8. Kimi K3 사용 조건

Kimi K3는 최소 $1 성공 충전 후 잠금 해제. 누적 충전액은 계정 등급과 rate limit 결정. Recharge and Rate Limits + K3 quickstart 참고.

9. Kimi K3의 reasoning effort 선택

K3는 항상 사고합니다. 최상위 reasoning_effort 필드로 low / high / max(기본 max) 설정. 복잡한 작업은 높은 단계, 단순 작업은 낮은 단계로 지연·토큰 소비 절감. 자세한 내용: Reasoning Effort.

10. K3의 chain-of-thought 끄기

끌 수 없습니다. K3는 항상 사고합니다. 사고가 너무 오래 걸린다면 reasoning_effort를 low로 줄이세요. Reasoning Effort 참고.

11. 충전 전 모델 테스트

Playground에서 모델·프롬프트 적합성 확인 가능. 코딩 중에는 MoonPalace 디버깅 도구로 완전한 요청을 캡처. Playground·계정 페이지가 실제 표시하는 모델과 바우처 커버리지가 우선입니다.

12. tool_calls에서 같은 도구 반복 호출

tool_calls 사용 시 모델은 컨텍스트에 따라 같은 도구를 여러 번 연속 호출할 수 있습니다.

같은 도구를 반복 호출하고, 매 호출이 정확히 같은 function.name·function.arguments이며 결과가 새 정보를 주지 않는다면, 이를 반복 호출로 간주할 수 있습니다.

메시지 레이아웃부터 확인:

Kimi API가 finish_reason=tool_calls를 반환하면, 반환된 choice.message를 그대로 messages 목록에 추가했는지
각 tool_call에 대응하는 role=tool 메시지가 있는지
role=tool 메시지의 tool_call_id가 대응 tool_call.id와 정확히 일치하는지
stream=True 스트리밍 출력을 쓴다면, tool_calls 청크가 올바르게 조립됐는지 (특히 function.arguments)

레이아웃이 맞는데도 동일 도구/인자가 반복되면, 클라이언트 측에서 반복 감지를 추가하고 다음 요청의 system prompt에 리마인더를 붙이세요.

3회 연속 반복 시:

<system-reminder>
You are repeating the exact same tool call with identical parameters. Please carefully analyze the previous result. If the task is not yet complete, try a different method or parameters instead of repeating the same call.
</system-reminder>

5회 연속 반복 시 (도구명/반복 횟수/인자 포함):

<system-reminder>
You have repeatedly called the same tool with identical parameters many times.
Repeated tool call detected:
- tool: {tool_name}
- repeated_times: {repeat_count}
- arguments: {tool_arguments}
The previous repeated calls did not make progress. Do not call this exact same tool with the exact same arguments again.
Carefully inspect the latest tool result and choose a different next action, different parameters, or finish the task if enough evidence has been gathered.
</system-reminder>

8회 연속 시 위 강한 리마인더를 다시 추가 권장.

<system-reminder>는 예시 프롬프트일 뿐 Kimi API의 특수 필드가 아닙니다. 다음 role=system 메시지에 병합하거나 자체 메시지 관리 로직에 따라 시스템 프롬프트에 기록하세요. 오탐 방지를 위해 같은 도구 + 같은 인자 + 연속 반복 + 결과에 새 진전 없음 조건이 모두 참일 때만 트리거하세요.

13. API 결과가 Kimi Assistant 결과와 다름

Kimi API와 Kimi Assistant는 다른 제품 경험입니다. 모델 버전·시스템 프롬프트·컨텍스트 관리·도구 설정·제품 정책이 다를 수 있어 동일 입력이 동일 출력을 보장하지 않습니다.

API 사용 시 모델 선택, 시스템 프롬프트 설정, 컨텍스트 관리, 필요한 도구 선언을 직접 해야 합니다. 사용 가능 모델과 파라미터 차이는 Model List, Model Parameter Reference 참고.

14. "웹 브라우징" 기능이 있나요?

⚠️ web_search 도구는 현재 업데이트 중. 당분간 사용을 권장하지 않습니다. 본 문서는 오래되었으며 후속 업데이트를 따르세요.

Kimi API는 내장 $web_search 도구를 제공합니다. 요청의 tools 필드에 builtin_function으로 선언하고 표준 tool_calls 흐름으로 결과를 처리하세요. 모든 API 요청에 웹 검색이 자동 활성화되지는 않습니다. 선언·전체 예제는 Use Web Search with the Kimi API 참고. 자체/서드파티 검색 서비스 연결은 Use the Kimi API for Tool Calls 참고.

15. API 결과가 불완전/잘림

응답 본문의 choice.finish_reason 확인. 값이 length면 현재 모델이 생성한 토큰 수가 요청의 max_completion_tokens를 초과한 것. Kimi API는 max_completion_tokens 토큰까지만 반환하고 나머지는 폐기.

finish_reason=length 시 이전 응답에서 이어서 받으려면 Partial Mode 사용. 가능하면 max_completion_tokens를 늘리세요. 권장: estimate-token-count API로 입력 토큰 수 계산 후 모델의 최대 컨텍스트 윈도우에서 빼기. 예: kimi-k3=1M, moonshot-v1-32k=32k, kimi-k2.6/kimi-k2.5/kimi-k2-0905-preview/kimi-k2-turbo-preview=256k.

16. 모델별 출력 길이

kimi-k3: 기본 max_completion_tokens = 131072, 최대 출력 = 1024*1024 - prompt_tokens
moonshot-v1-8k: 8*1024 - prompt_tokens
moonshot-v1-32k: 32*1024 - prompt_tokens
moonshot-v1-128k: 128*1024 - prompt_tokens
kimi-k2.6 / kimi-k2.5 / kimi-k2-0905-preview / kimi-k2-turbo-preview: 256*1024 - prompt_tokens

17. 한자 지원량

kimi-k3: 약 1,500,000자
moonshot-v1-8k: 약 15,000자
moonshot-v1-32k: 약 60,000자
moonshot-v1-128k: 약 200,000자
kimi-k2.6 / kimi-k2.5 / kimi-k2-0905-preview / kimi-k2-turbo-preview: 약 400,000자

추정치. 실제 결과는 다를 수 있음.

18. 파일 추출 부정확/이미지 인식 불가

다양한 파일 포맷의 업로드·파싱 서비스 제공. 텍스트 파일은 텍스트 추출, 이미지 파일은 OCR로 텍스트 인식, PDF는 이미지 기반이면 OCR, 아니면 텍스트만 추출.

이미지의 경우 OCR로 텍스트만 추출합니다. 텍스트가 없는 이미지면 파싱 실패. 지원 포맷 전체 목록: Files Upload API.

19. file_id로 파일 내용 참조

현재 file file_id로 파일 내용을 컨텍스트로 참조하는 것은 지원되지 않음.

20. content_filter 오류

Kimi API 입력 또는 모델 출력에 안전하지 않거나 민감한 내용이 포함될 때 발생. 모델이 생성한 출력도 안전하지 않거나 민감한 내용을 포함할 수 있어 content_filter 오류를 발생시킬 수 있습니다.

서드파티 플랫폼/도구를 통해 호출 중이라면 오류가 정말 Kimi API에서 반환된 것인지 먼저 확인. 서드파티는 자체 콘텐츠 안전 정책/오류 문구를 적용할 수 있어 메시지가 반드시 Kimi API에서 온 것은 아닙니다. 플랫폼은 트리거된 정확한 안전 규칙을 공개할 수 없습니다. 요청 범위를 좁히고 오탐을 유발할 수 있는 내용을 제거한 뒤 재시도하세요.

21. 연결 관련 오류

자주 Connection Error / Connection Time Out이 발생하면 다음을 순서대로 확인:

프로그램/SDK에 기본 타임아웃 설정이 있는지
프록시 서버 사용 여부와 그 네트워크/타임아웃 설정

또 다른 원인: stream=True 스트리밍 없이 너무 많은 토큰을 생성. 이 경우 응답이 완료될 때까지 기다리면서 중간 게이트웨이가 타임아웃으로 연결을 끊을 수 있음. 일부 게이트웨이는 서버가 status_code/header를 보냈는지 확인해 유효 요청을 판단합니다. stream=True가 아니면 Kimi 서버는 생성을 끝낸 뒤 header를 보냅니다. 그 header를 기다리는 동안 일부 게이트웨이는 장시간 연결을 닫아 연결 오류가 발생할 수 있습니다.

stream=True로 스트리밍 출력을 활성화해 연결 관련 오류를 가능한 한 줄이세요.

22. 에러 메시지의 TPM/RPM 한도가 내 등급과 다름

예시:

rate_limit_reached_error: Your account {uid}<{ak-id}> request reached TPM rate limit, current:{current_tpm}, limit:{max_tpm}

대시보드의 TPM/RPM과 다르면 먼저 현재 계정에 맞는 api_key를 쓰는지 확인. 대부분 다른 사용자의 Key 또는 여러 계정의 Key를 섞어 쓰는 경우 발생.

23. model_not_found 오류

SDK가 base_url=https://api.moonshot.ai/v1로 설정됐는지 확인. base_url 없이 OpenAI SDK를 쓰면 요청이 OpenAI 서버로 가서 model_not_found를 반환.

24. 모델이 수치 계산 오류를 일으킴

모델 생성의 불확실성 때문에 Kimi 모델은 수치 계산에서 다양한 심각도의 오류를 일으킬 수 있습니다. tool_calls로 계산기 기능을 제공하는 것을 권장. 자세한 내용: Use the Kimi API for Tool Calls (tool_calls).

25. 모델이 오늘 날짜를 모름

Kimi 모델은 현재 날짜 같은 고도의 시간 민감 정보에 접근할 수 없습니다. 시스템 프롬프트에 정보를 제공하세요.

import os
from datetime import datetime
from openai import OpenAI

client = OpenAI(
    api_key=os.environ['MOONSHOT_API_KEY'],
    base_url="https://api.moonshot.ai/v1",
)

system_prompt = f"""
You are Kimi, and today's date is {datetime.now().strftime('%d.%m.%Y %H:%M:%S')}
"""

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "What is today's date?"},
    ],
)

print(completion.choices[0].message.content)  # Output: Today's date is July 31, 2024.

26. SDK 없이 오류 처리

HTTP 상태 200은 성공, 4xx/5xx는 실패를 나타냅니다. 오류는 JSON 형식:

import os
import httpx

header = {
    "Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}",
}

messages = [
    {"role": "system", "content": "You are Kimi"},
    {"role": "user", "content": "Hello."},
]

r = httpx.post("https://api.moonshot.ai/v1/chat/completions",
               headers=header,
               json={
                   "model": "kimi-k3",  # 올바른 모델 → status_code == 200 분기
                   # "model": "moonshot-v1-129k",  # 잘못된 모델 → else 분기
                   "messages": messages,
               })

if r.status_code == 200:
    completion = r.json()
    print(completion["choices"][0]["message"]["content"])
else:
    error = r.json()
    print(f"error: status={r.status_code}, type='{error['error']['type']}', message='{error['error']['message']}'")

오류 형식:

{
	"error": {
		"type": "error_type",
		"message": "error_message"
	}
}

전체 오류 레퍼런스: Error Reference.

27. 비슷한 프롬프트인데 응답 속도가 들쭉날쭉

생성된 토큰 수가 달라서 발생. 일반적으로 생성 토큰 수는 Kimi API의 총 응답 시간에 비례합니다. 토큰 수가 많을수록 응답 완료까지 시간이 더 깁니다.

stream=True로 설정해 time-to-first-token(TTFT)을 관찰하세요. 프롬프트 길이가 비슷할 때 TTFT는 크게 달라지지 않습니다.

28. max_completion_tokens=2000인데 출력이 더 짧음

max_tokens는 deprecated. max_completion_tokens를 사용하세요. 의미는 동일.

max_completion_tokens는 모델이 생성할 수 있는 최대 토큰 수. 초과 시 모델은 다음 토큰 생성을 멈춥니다.

용도:

모델 선택 판단 (예: prompt_tokens + max_completion_tokens <= 8 * 1024 → moonshot-v1-8k 선택)
비정상적인 대량 생성 방지 (예: 모델이 공백을 반복)

max_completion_tokens는 모델의 입력 프롬프트 일부로 사용되지 않습니다. 특정 글자 수를 원하면 다음 접근:

1,000자 미만: 프롬프트에 글자 수 명시 + 길이 검증 후 짧으면 다시 생성 요청

1,000자 이상: 템플릿/플레이스홀더로 분할 생성 후 조립

29. 1분 요청 1건인데도 `Your account reached max request` 발생

OpenAI SDK는 기본적으로 일부 오류(connection error, 408, 409, 429, 5xx+)에 대해 2회 자동 재시도합니다. 단일 요청이 3회로 증폭되어 RPM 할당량을 빠르게 소진할 수 있습니다.

tier0 계정 + OpenAI SDK 조합에서는 단일 실패 요청이 기본 재시도 메커니즘으로 인해 전체 RPM 할당량을 소진할 수 있습니다.

30. base64 인코딩으로 텍스트 전송

base64로 텍스트 파일을 인코딩하지 마세요. 토큰 소비가 폭증합니다. 지원되는 파일 타입은 /v1/files API로 업로드한 뒤 추출하세요.

이진 파일/기타 인코딩 포맷은 Kimi 모델이 현재 파싱 불가. 컨텍스트에 추가하지 마세요.

31. 다른 Kimi 플랫폼의 Key를 platform.kimi.ai에 사용할 수 없음

Kimi Open Platform은 지역별로 별도 플랫폼을 운영합니다. 중국 본토 외 사용자는 platform.kimi.ai를 사용. 지역 간 계정/Key는 격리.

잘못된 Key 사용 시 401 invalid_authentication_error. 국제판 base_url: https://api.moonshot.ai/v1.

변경 이력

날짜	변경
2026-07-22	초판 작성 (공식 Troubleshooting 가이드 한글화)
2026-07-22	제목에 "Kimi" 접두사 추가, 본문 H1 중복 제거