エラーコードリファレンス

Claude Code の一般的なエラーコードと解決策

このドキュメントでは、Claude Code 使用中に遭遇する可能性のある様々なエラーコードとその解決策を詳しく説明します。

エラーコード早見表¶

429 - リクエスト過多（Too Many Requests）¶

最も一般的なエラーの1つで、短時間に多くのリクエストが送信されたことを示します。

エラーメッセージ¶

Error: 429 Too Many Requests
Rate limit exceeded. Please slow down your requests.

一般的な原因¶

1. リクエストが頻繁すぎる：連続して急速にリクエストを送信

2. 並行リクエストが多すぎる：複数の Claude Code インスタンスを同時実行

3. トークン制限に達した：短時間で大量のトークンを消費

4. クォータ枯渇：日次/月次クォータを使い切った

解決策¶

即時対応：

# 30-60秒待ってから再試行
sleep 60 && claude "あなたの質問"

長期的な対策：

1. リクエスト頻度を下げ、連続した急速な送信を避ける

2. /compact コマンドでコンテキストを圧縮

3. 大きなタスクを小さなバッチに分割

4. より高いクォータのプランへのアップグレードを検討

QCode.cc の優位性：専門的なロードバランシング、マルチアカウントプールでリクエスト圧力を分散、429 エラーを効果的に削減。

502 - ゲートウェイエラー（Bad Gateway）¶

ゲートウェイまたはプロキシサーバーが上流から無効な応答を受信したことを示します。

エラーメッセージ¶

Error: 502 Bad Gateway
The server received an invalid response from the upstream server.

一般的な原因¶

1. 上流が一時的に利用不可：Anthropic API サーバーの問題

2. ネットワーク接続が中断：リクエスト中に接続が切断

3. プロキシサーバーの問題：中間ノードの障害

4. リクエストタイムアウト：応答時間がゲートウェイ制限を超過

解決策¶

即時対応：

# ネットワーク接続を確認
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# 待ってから再試行
sleep 30 && claude "あなたの質問"

長期的な対策：

1. ローカルネットワークの安定性を確認

2. ネットワーク環境の切り替えを試す

3. VPN またはより安定したネットワークを使用

4. 持続する場合はサポートに連絡

QCode.cc の優位性：マルチリージョンデプロイメント、CDN アクセラレーション、自動フェイルオーバー、99.9% の可用性を保証。

401 - 認証失敗（Unauthorized）¶

API Key が無効または有効な認証情報が提供されていません。

エラーメッセージ¶

Error: 401 Unauthorized
Invalid API key or authentication token.

一般的な原因¶

1. API Key が間違っている：コピー時に文字が欠落または余分なスペース

2. API Key の期限切れ：サブスクリプションが期限切れ

3. API Key が無効化：ポリシー違反により禁止

4. 環境変数未設定：ANTHROPIC_AUTH_TOKEN が設定されていない

解決策¶

API Key を検証：

# 環境変数を確認
echo $ANTHROPIC_AUTH_TOKEN

# 正しい形式を確認（cr_ で始まる）
# 正しい例：cr_xxxxxxxxxxxxxxxxxxxx

手順：

1. QCode.cc ダッシュボード にログインして API Key のステータスを確認

2. サブスクリプションが有効であることを確認

3. 禁止された場合はサポートに連絡（QCode.cc は即時交換サービスを提供）

402 - 支払いが必要（Payment Required）¶

上流チャネルがこのリクエストを拒否しました。多くの場合、キーや設定の問題ではありません —— 同じキーから同じ時間帯に別のモデルへ送ったリクエストは通常どおり成功します。

症状¶

Error: 402 Payment Required

Claude Code では応答が何も返らずリクエストが失敗する形で現れ、スクリプトや SDK では HTTP 402 になります。

よくある原因¶

1. 上流チャネルが一時的に利用できない：QCode のゲートウェイ自身は 402 を生成せず、上流が返したステータスをそのまま渡しています

2. 特定のモデルに集中する：同じ時間帯でも、あるモデルだけ 402 の比率が高く、他のモデルはまったく正常ということがあります

3. 接続ドメインによって差が出る：ドメインごとに経由する上流経路が異なり、402 に当たる確率が大きく変わることがあります

4. 残高とは無関係：残高やプラン枠を使い切っても 402 にはなりません。その場合は「1日の利用上限に達しました」という表示になります（よくある質問（FAQ） を参照）

対処¶

① モデルを切り替える（最も有効）

# セッション内で切り替え
/model sonnet

# 起動時に指定
claude --model claude-sonnet-5

② 接続ドメインを切り替える

# 中国本土
export ANTHROPIC_BASE_URL=https://asia.qcode.cc/api

# グローバル（Route 53 が最寄りを選択）
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api

4 つのドメインは同じキーで使えるため、切り替えに他の設定変更は不要です。エンドポイントと API フォーマット を参照してください。

③ 密なリトライループを書かない

402 はすぐ再送しても解消しません。詰めて再試行すると状況が悪化するだけです。指数バックオフを使うか、モデルを切り替えてください（本ページの「エラー処理のベストプラクティス」参照）。

④ 続くようならサポートへ

発生時刻・モデル id・接続ドメインを添えて、オンラインサポート または hi@qcode.cc までご連絡ください。

INSUFFICIENT_BALANCE / Insufficient account balance¶

402/403 のレスポンスに "code":"INSUFFICIENT_BALANCE", "message":"Insufficient account balance" という JSON が載ることがあります。QCode の残高が尽きたという意味ではありません——上流チャネルの一時状況をそのまま中継したもので、あなたのアカウントとは無関係です。自分の利用枠を使い切った場合に表示されるのは「日次費用上限に到達」という案内です（FAQ 参照）。

対処：少し待って再試行 / モデル切替 / 接続ドメイン切替（上の ①–③ がそのまま使えます）。繰り返す場合は request id を添えてサポートへ。全体の手順はトラブルシューティングガイド。

403 - 権限エラー（Forbidden）¶

サーバーによってリクエストが拒否されました。通常は権限不足が原因です。

エラーメッセージ¶

Error: 403 Forbidden
You don't have permission to access this resource.

一般的な原因¶

1. API エンドポイントが間違っている：間違った API アドレスを使用

2. 権限不足：現在のプランがこの機能をサポートしていない

3. 地域制限：一部の機能が特定の地域で利用不可

4. アカウントステータスの問題：アカウントが制限されている

解決策¶

# API エンドポイントが正しいことを確認
echo $ANTHROPIC_BASE_URL
# 正しい値：https://api.qcode.cc/api

1. API エンドポイント設定を確認

2. プランに必要な機能が含まれていることを確認

3. サポートに連絡して権限を確認

INSUFFICIENT_BALANCE（403 で出た場合）¶

403 Forbidden の本文に INSUFFICIENT_BALANCE / Insufficient account balance が入っている場合、これも上流チャネルの一時状況の透過であることが多く、アカウント制限ではありません。402 節の同名小節の手順で対処してください。切り分け順序はトラブルシューティングガイド参照。

400 - リクエストエラー（Bad Request）¶

リクエスト形式が正しくないか、パラメータが無効です。

エラーメッセージ¶

Error: 400 Bad Request
The request was malformed or contained invalid parameters.

一般的な原因¶

1. リクエスト形式エラー：JSON 形式が正しくない

2. パラメータ欠落：必須パラメータが提供されていない

3. 無効な値：パラメータ値が許可範囲外

4. エンコーディング問題：特殊文字が正しくエンコードされていない

解決策¶

# 入力に特殊文字がないか確認
# リクエスト内容が正しくフォーマットされていることを確認
claude -p "簡単なテスト"

1. 入力を簡素化し、特殊文字を除外

2. ファイルパスが正しいエンコーディングを使用していることを確認

3. コマンドパラメータ形式を確認

500 - サーバー内部エラー（Internal Server Error）¶

サーバーが予期しない状況に遭遇し、リクエストを完了できませんでした。

エラーメッセージ¶

Error: 500 Internal Server Error
An unexpected error occurred on the server.

一般的な原因¶

1. サーバー側のバグ：API サーバーコードの問題

2. リソース枯渇：サーバーリソースが一時的に不足

3. 設定エラー：サーバーの設定ミス

解決策¶

# 待ってから再試行
sleep 60 && claude "あなたの質問"

# 詳細情報を取得するために verbose モードを使用
claude --verbose

1. 数分待ってから再試行

2. QCode.cc のサービスステータスを確認

3. 持続する場合はエラー詳細を添えてサポートに連絡

E015 - 会話コンテキストオーバーフロー¶

会話コンテキストがモデルの容量上限（~95%）に近づいたときに発生します。QCode.cc はこのエラーを 429 レスポンスとしてラップし、再試行を促します：

429 {"error":{"code":"E015","message":"Internal server error"},"status":500}

解決策：コンテキスト管理 の「長いセッションのオーバーフロー防止」セクションをご参照ください。

503 - サービス利用不可（Service Unavailable）¶

サーバーが一時的にリクエストを処理できません。通常は過負荷またはメンテナンスが原因です。

エラーメッセージ¶

Error: 503 Service Unavailable
The service is temporarily unavailable. Please try again later.

一般的な原因¶

1. サーバー過負荷：リクエスト量が容量を超過

2. 定期メンテナンス：サーバーがメンテナンス中

3. リソース枯渇：サーバーリソースが一時的に不足

解決策¶

# 指数バックオフで再試行
for i in 1 2 4 8 16; do
  claude "あなたの質問" && break
  echo "再試行中、${i} 秒待機..."
  sleep $i
done

1. 数分待ってから再試行

2. 指数バックオフ再試行戦略を使用

3. サービスステータスの発表を確認

529 - API 過負荷（Overloaded）¶

Claude API 固有のエラーコードで、API サービスの過負荷を示します。

エラーメッセージ¶

Error: 529 Overloaded
The API is temporarily overloaded. Please try again later.

一般的な原因¶

1. グローバル使用量の急増：Claude サービスの世界的なユーザー増加

2. ピーク時間：勤務時間中にリクエストが集中

3. 人気イベント：特定のイベントによる使用量の急増

解決策¶

# 後で再試行
sleep 120 && claude "あなたの質問"

1. 2-5分待ってから再試行

2. ピーク時間を避ける（米国の営業時間）

3. /compact を使用してトークン使用量を削減

QCode.cc の優位性：マルチアカウントプールローテーション機構で過負荷圧力を効果的に分散。

接続タイムアウト（Connection Timeout）¶

リクエストが指定時間内に完了できませんでした。

エラーメッセージ¶

Error: Connection timed out
The request timed out while waiting for a response.

一般的な原因¶

1. ネットワーク不安定：ネットワーク接続品質が低い

2. リクエストが大きすぎる：コンテキストトークンが多すぎる

3. タスクが複雑すぎる：AI 処理時間が長すぎる

4. サーバー応答が遅い：サーバー負荷が高い

解決策¶

# ネットワーク接続をテスト
ping api.qcode.cc

# コンテキストを減らすために compact モードを使用
/compact

1. ネットワーク接続の安定性を確認

2. /compact を使用してコンテキストを圧縮

3. 複雑なタスクをより簡単なものに分割

4. より安定したネットワーク環境を試す

MCP サーバーエラー¶

MCP サーバーの設定または実行時に発生する可能性のあるエラーです。

エラーの内容¶

MCP server "xxx" failed to start
MCP connection timed out
MCP tool execution failed

よくある原因¶

1. サーバーコマンドの誤り：npx パッケージ名のミスまたは未インストール

2. 環境変数の未設定：MCP サーバーが必要とするトークンが未設定

3. タイムアウト：サーバー起動または実行に時間がかかりすぎ

4. 権限不足：ファイルシステム／データベースへのアクセス拒否

解決策¶

# Check server status with /mcp
/mcp

# Diagnose configuration issues with /doctor
/doctor

# Manually test whether the MCP server can start
npx -y @modelcontextprotocol/server-filesystem /tmp

1. /mcp で接続状態を確認

2. /doctor で自動診断を実行

3. ~/.claude/settings.json または .mcp.json の形式を確認

4. 必要な環境変数（$GITHUB_TOKEN など）が設定されているか確認

5. MCP_TIMEOUT と MCP_TOOL_TIMEOUT 環境変数でタイムアウトを延長

一般的なトラブルシューティング手順¶

エラーが発生したら、以下の手順に従ってください：

0. 自動診断を実行する¶

# Claude Code's built-in diagnostic tool
/doctor

環境変数・API 接続・MCP サーバーの状態など、よくある設定問題を自動チェックします。

1. ネットワーク接続を確認¶

# API エンドポイントの接続性をテスト
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models

# DNS 解決をテスト
nslookup api.qcode.cc

2. 環境変数を確認¶

# すべての関連環境変数を確認
echo "BASE_URL: $ANTHROPIC_BASE_URL"
echo "AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN:0:10}..."

3. 詳細ログを有効化¶

# 詳細情報のために verbose モードを使用
claude --verbose

# またはデバッグモードを設定
DEBUG=true claude

4. 簡単なリクエストをテスト¶

# 簡単なテストリクエストを送信
claude -p "こんにちは"

5. サービスステータスを確認¶

QCode.cc でサービスステータスの発表を確認してください。

エラーハンドリングのベストプラクティス¶

再試行メカニズムの実装¶

# 簡単な再試行スクリプト
retry_claude() {
  local max_attempts=3
  local attempt=1

  while [ $attempt -le $max_attempts ]; do
    claude "$@" && return 0
    echo "試行 $attempt 失敗、再試行中..."
    sleep $((attempt * 2))
    ((attempt++))
  done

  echo "すべての試行が失敗しました"
  return 1
}

使用量の監視¶

クォータ超過を避けるために定期的に API 使用量を確認：

1. QCode.cc ダッシュボード にログイン

2. 使用統計を表示

3. 使用量アラートを設定

リクエストの最適化¶

1. コンテキストを減らす：定期的に /compact または /clear を使用

2. バッチ処理：大きなタスクを小さなものに分割

3. 重複を避ける：一般的な結果をキャッシュ

ヘルプを取得¶

上記の解決策で問題が解決しない場合は、QCode.cc サポートにお問い合わせください：

• ライブチャット：ウェブサイト右下隅

• 応答時間：営業時間内 1-2 時間

• サポート時間：7×14（毎日 9:00 - 23:00）

サポートに連絡する際は、以下を提供してください：

1. 完全なエラーメッセージ

2. 実行したコマンド

3. 発生時刻

4. API Key プレフィックス（完全なキーは共有しないでください）