Kimi API のエラーでは、まず 3 つを見ます。HTTP ステータスコード、error.type、request_id です。同じ 429 でも、サーバー側の過負荷、組織のレート制限、残高不足の可能性があります。同じ 401 でも、キーの書き間違い、中国サイトと国際サイトの混用の可能性があります。まず分類し、それからコードを変更してください。
本記事では 401、404、429、タイムアウトの 4 種類に分け、原因、調査手順、再利用可能なバックオフ コードを示します。モデルと価格は本サイトのモデル価格を基準とします。
注記：Moonshot、Kimi はその権利者の商標です。エラー種別、レート制限規則、インターフェースの挙動は変更される可能性があります。本記事は 2026 年 10 月時点の一般的な状況を例にしており、最終的には公式ドキュメントを基準とします。
一、ステータスコード早見表
| ステータスコード | エラー種別 | 一般的な意味 | 対応の方向 |
|---|---|---|---|
| 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 を記録し、完全なキーと機密内容は記録しないでください。
二、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 を返せば、キー、地域、モデル名の 3 項目が通っています。それでも 401 が返る場合は、動作確認済みの別のキーで試し、キー自体の問題かゲートウェイ設定の問題かを切り分けます。
三、404：モデル名と base_url の誤りが最も多い
404 は必ずしもモデル廃止とは限らず、よくある原因は 4 種類です。
- OpenAI SDK を使うときに
base_urlを設定せず、デフォルトの OpenAI アドレスへ送ってしまい、モデルが存在しないと返される。 - モデル名の綴り誤り、またはアカウントが現在アクセス権を持たないモデルの指定。
- パスに
/v1が多いか少ない、またはチャット以外のパスを指定している。 - 中国サイトと国際サイトでモデル名と権限が異なる。
まず同じキーでモデル一覧を取得し、アカウントから何が見えるかを確認します。
curl "https://api.moonshot.cn/v1/models" \
-H "Authorization: Bearer $MOONSHOT_API_KEY"
一覧にないモデルを推測で使わないでください。モデルの可用性は、アカウントの実際の戻り値と本サイトのモデル価格を基準とします。モデル一覧は返るのにチャットが 404 になる場合は、パスに /v1 が欠けていないか、クライアントが base_url と完全パスを二重に結合していないかを確認します。
四、429：3 種類で対応が異なる
error.type |
意味 | リトライ可否 | 対応 |
|---|---|---|---|
engine_overloaded_error |
サーバー側の過負荷 | 可能 | Retry-After に従ってバックオフし、同時実行を下げる |
rate_limit_reached_error |
組織レベルの同時実行、RPM、TPM、TPD の超過 | 一部可能 | 速度を下げる、キーを分割する、クラスを上げる |
exceeded_current_quota_error |
未払い、残高不足、クーポン失効 | 不可 | チャージまたは請求を確認 |
TPD の超過は通常、翌日まで待つか上限を引き上げるしかなく、リトライを続けても意味がありません。429 で中断されたリクエストは通常課金されませんが、リトライが成功すれば通常どおり課金されます。費用を恐れて無限にリトライせず、429 を見ただけで口座から引き落とされたと判断しないでください。OpenAI SDK はデフォルトで自動リトライするため、1 回の 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("リトライ回数を使い切りました")
リトライは一時的なエラーにのみ適しています。すでに副作用が発生した業務では、冪等キーまたは状態確認で実行済みかどうかを確かめてから、再送の可否を決めます。
五、タイムアウトと 504
長文生成、長文書分析、コード Agent で最もタイムアウトが起きやすいです。処理の順序は次のとおりです。
- 非ストリーミングを
stream=Trueに変更し、接続が継続的にデータを返すようにする。 - 適切な接続タイムアウトと読み取りタイムアウトを設定し、SDK のデフォルト値を流用しない。
- 社内プロキシ、ゲートウェイ、ローカルルーティングツールが接続を早めに切断していないか確認する。この場合は 499 として現れることがある。
max_completion_tokensで 1 回の出力長を制御し、超長タスクは分割して処理する。- タイムアウトごとにリクエスト 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="")
ストリーミングは単価を下げませんが、「タイムアウトまで待ってからリトライする」無駄を大幅に減らせます。接続タイムアウトは短めに、読み取りタイムアウトは最長の生成時間に合わせて設定します。ストリーミングでは非ストリーミング用の読み取りタイムアウトを流用しないでください。正常な生成中にクライアント自身が接続を切ってしまいます。
六、調査順序の表
- ステータスコード、
error.type、request_id、モデル名、発生日時を記録する。 - 401、403 は地域、キー、製品ライン、権限、残高を確認する。
- 404 は
base_url、モデル名、アカウント権限を確認し、モデル一覧で検証する。 - 400 はコンテキスト長、出力上限、ファイル形式、コンテンツ安全を確認する。
- 429 は
error.typeで過負荷、レート制限、未払いの 3 種類に分けて処理する。 - 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 Gateway でテストキーを作成し、401、404、429、タイムアウトをそれぞれ 1 回ずつ演習してから、本番監視に接続します。モデルの可用性と価格はモデル価格を基準とします。
関連記事：
