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

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

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

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

エラーコード早見表 ¶

コード	タイプ	説明	重大度
400	クライアントエラー	リクエスト形式エラー	低
401	認証エラー	API Key 無効	中
403	権限エラー	アクセス拒否	中
429	レート制限	リクエスト過多	中
500	サーバーエラー	内部エラー	高
502	ゲートウェイエラー	上流サービス不可	高
503	サービス利用不可	一時的な過負荷	高
529	API 過負荷	Claude API 過負荷	高

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

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

エラーメッセージ ¶

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

一般的な原因 ¶

リクエストが頻繁すぎる：連続して急速にリクエストを送信
並行リクエストが多すぎる：複数の Claude Code インスタンスを同時実行
トークン制限に達した：短時間で大量のトークンを消費
クォータ枯渇：日次/月次クォータを使い切った

解決策 ¶

即時対応：

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

長期的な対策：

リクエスト頻度を下げ、連続した急速な送信を避ける
/compact コマンドでコンテキストを圧縮
大きなタスクを小さなバッチに分割
より高いクォータのプランへのアップグレードを検討

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

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

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

エラーメッセージ ¶

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

一般的な原因 ¶

上流が一時的に利用不可：Anthropic API サーバーの問題
ネットワーク接続が中断：リクエスト中に接続が切断
プロキシサーバーの問題：中間ノードの障害
リクエストタイムアウト：応答時間がゲートウェイ制限を超過

解決策 ¶

即時対応：

# ネットワーク接続を確認
curl -I https://asia.qcode.cc/api

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

長期的な対策：

ローカルネットワークの安定性を確認
ネットワーク環境の切り替えを試す
VPN またはより安定したネットワークを使用
持続する場合はサポートに連絡

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

401 - 認証失敗（Unauthorized）¶

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

エラーメッセージ ¶

Error: 401 Unauthorized
Invalid API key or authentication token.

一般的な原因 ¶

API Key が間違っている：コピー時に文字が欠落または余分なスペース
API Key の期限切れ：サブスクリプションが期限切れ
API Key が無効化：ポリシー違反により禁止
環境変数未設定：ANTHROPIC_AUTH_TOKEN が設定されていない

解決策 ¶

API Key を検証：

# 環境変数を確認
echo $ANTHROPIC_AUTH_TOKEN

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

手順：

QCode.cc ダッシュボードにログインして API Key のステータスを確認
サブスクリプションが有効であることを確認
禁止された場合はサポートに連絡（QCode.cc は即時交換サービスを提供）

403 - 権限エラー（Forbidden）¶

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

エラーメッセージ ¶

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

一般的な原因 ¶

API エンドポイントが間違っている：間違った API アドレスを使用
権限不足：現在のプランがこの機能をサポートしていない
地域制限：一部の機能が特定の地域で利用不可
アカウントステータスの問題：アカウントが制限されている

解決策 ¶

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

API エンドポイント設定を確認
プランに必要な機能が含まれていることを確認
サポートに連絡して権限を確認

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

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

エラーメッセージ ¶

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

一般的な原因 ¶

リクエスト形式エラー：JSON 形式が正しくない
パラメータ欠落：必須パラメータが提供されていない
無効な値：パラメータ値が許可範囲外
エンコーディング問題：特殊文字が正しくエンコードされていない

解決策 ¶

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

入力を簡素化し、特殊文字を除外
ファイルパスが正しいエンコーディングを使用していることを確認
コマンドパラメータ形式を確認

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

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

エラーメッセージ ¶

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

一般的な原因 ¶

サーバー側のバグ：API サーバーコードの問題
リソース枯渇：サーバーリソースが一時的に不足
設定エラー：サーバーの設定ミス

解決策 ¶

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

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

数分待ってから再試行
QCode.cc のサービスステータスを確認
持続する場合はエラー詳細を添えてサポートに連絡

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.

一般的な原因 ¶

サーバー過負荷：リクエスト量が容量を超過
定期メンテナンス：サーバーがメンテナンス中
リソース枯渇：サーバーリソースが一時的に不足

解決策 ¶

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

数分待ってから再試行
指数バックオフ再試行戦略を使用
サービスステータスの発表を確認

529 - API 過負荷（Overloaded）¶

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

エラーメッセージ ¶

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

一般的な原因 ¶

グローバル使用量の急増：Claude サービスの世界的なユーザー増加
ピーク時間：勤務時間中にリクエストが集中
人気イベント：特定のイベントによる使用量の急増

解決策 ¶

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

2-5分待ってから再試行
ピーク時間を避ける（米国の営業時間）
/compact を使用してトークン使用量を削減

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

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

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

エラーメッセージ ¶

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

一般的な原因 ¶

ネットワーク不安定：ネットワーク接続品質が低い
リクエストが大きすぎる：コンテキストトークンが多すぎる
タスクが複雑すぎる：AI 処理時間が長すぎる
サーバー応答が遅い：サーバー負荷が高い

解決策 ¶

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

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

ネットワーク接続の安定性を確認
/compact を使用してコンテキストを圧縮
複雑なタスクをより簡単なものに分割
より安定したネットワーク環境を試す

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

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

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

# API エンドポイントの接続性をテスト
curl -I https://asia.qcode.cc/api

# DNS 解決をテスト
nslookup asia.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
}