AI APIリクエストログ分析と問題切り分け完全ガイド

AI APIを使っていると、「なぜ動かないの？」と頭を悩ませることがあるでしょう。私も最初の頃は、エラーコードを見るたびにパニックになっていました。でも、ログの読み方を覚えたら90%の問題を自力で解決できるようになりました。この記事では、APIログ初心者のために、基本から実践まで丁寧に説明します。

そもそも「ログ」って何？

ログとは、APIに送ったリクエストと返ってきた答えの「記録簿」です。ドラマで例えるなら、出演者（クライアント）と相手役（サーバー）の掛け合いを全部書き出した台本のようなものです。

• リクエストログ：あなたがAPIに送った内容（いつ、何を求めたか）
• レスポンスログ：APIが返してきた内容（成功したか、エラーだったか）
• エラーログ：問題が発生した時の詳細記録

【ヒント】 браузерの「開発者ツール」→「Network」タブを開くと、WebページからAPIへの通信をリアルタイムで確認できます。F12キーを押して試してみましょう！

HolySheep AIのAPIを試してみよう

まずは実際にAPIを叩いて、ログを見てみるのが一番の近道です。今すぐ登録して無料クレジットを手に入れましょう。HolySheep AIなら、レートが¥1=$1と公式价比べて85%もお得です！

curlで simplest なリクエストを送る

コマンドライン（ターミナル）に以下のコードを入力してみてください。 HolySheep AIの base_url は https://api.holysheep.ai/v1 固定です。

curl https://api.holysheep.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HOLYSHEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "こんにちは"}],
    "max_tokens": 100
  }'

【ヒント】WindowsではPowerShell、Mac/Linuxでは標準のターミナルを使います。「cmd.exe」や「Terminal」で起動してみましょう。

成功すると、こんな感じのJSONが返ってきます：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "こんにちは！有什么我可以帮助你的吗？"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 25,
    "total_tokens": 35
  }
}

Pythonで確認ログを出力する方法

PythonからAPIを呼び出す際に、リクエストとレスポンスの詳細を全てコンソールに出力する万能スクリプト紹介します。

import requests
import json
import time

BASE_URL = "https://api.holysheep.ai/v1"

def log_request(method, url, headers, data=None):
    """リクエストの詳細をログ出力"""
    print("=" * 60)
    print(f"[REQUEST] {method} {url}")
    print(f"[TIME] {time.strftime('%Y-%m-%d %H:%M:%S')}")
    print(f"[HEADERS] {json.dumps(headers, ensure_ascii=False, indent=2)}")
    if data:
        print(f"[BODY] {json.dumps(data, ensure_ascii=False, indent=2)}")
    print("-" * 60)

def log_response(response):
    """レスポンスの詳細をログ出力"""
    print(f"[STATUS] {response.status_code} {response.reason}")
    print(f"[TIME] {time.strftime('%Y-%m-%d %H:%M:%S')}")
    print(f"[HEADERS] {json.dumps(dict(response.headers), ensure_ascii=False, indent=2)}")
    print(f"[BODY] {json.dumps(response.json(), ensure_ascii=False, indent=2)}")
    print("=" * 60)
    return response

def call_ai_api(api_key, model, prompt):
    """HolySheep AI APIを呼び出してログも出力"""
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
        "max_tokens": 500,
        "temperature": 0.7
    }
    
    log_request("POST", f"{BASE_URL}/chat/completions", headers, data)
    
    start_time = time.time()
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=data,
        timeout=30
    )
    elapsed_ms = (time.time() - start_time) * 1000
    
    log_response(response)
    print(f"[LATENCY] 応答時間: {elapsed_ms:.2f}ms")
    
    return response.json()

使用例
if __name__ == "__main__":
    API_KEY = "YOUR_HOLYSHEEP_API_KEY"
    result = call_ai_api(
        api_key=API_KEY,
        model="gpt-4o-mini",
        prompt="日本の美味しい拉麺の有名な店について教えて"
    )

このスクリプトを実行すると、こんなログが出力されます：

============================================================
[REQUEST] POST https://api.holysheep.ai/v1/chat/completions
[TIME] 2025-01-15 14:30:45
[HEADERS] {
  "Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY",
  "Content-Type": "application/json"
}
[BODY] {
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "日本の美味しい拉麺の有名な店について教えて"}],
  "max_tokens": 500,
  "temperature": 0.7
}
------------------------------------------------------------
[STATUS] 200 OK
[TIME] 2025-01-15 14:30:45
[HEADERS] {
  "content-type": "application/json",
  "x-ratelimit-remaining": "99",
  "x-ratelimit-reset": "1705329000"
}
[BODY] {
  "id": "chatcmpl-xyz789",
  "object": "chat.completion",
  "created": 1705329045,
  "model": "gpt-4o-mini",
  "choices": [...],
  "usage": {...}
}
============================================================
[LATENCY] 応答時間: 42.35ms

【ヒント】x-ratelimit-remainingは「このAPIキーを使うと、あと何回リクエストできるか」を示しています。0になる前に、新しいリクエストの間隔を空けましょう。

ログから読み解くHTTPステータスコード

APIが返す3桁の数字（ステータスコード）を覚えると、問題の80%がすぐ解決します。

• 200：成功！何も問題なし
• 400：リクエストの書き方が間違っている（入力ミスの可能性大）
• 401：APIキーが無効，或者是有効期限切れ
• 403：アクセス権限がない（ model's 利用不可など）
• 429：リクエストが多すぎる（レートリミット超過）
• 500：サーバー側の一時的な問題
• 503：メンテナンス中，或者是過負荷状態

覚えておきたい重要ログ項目

1. usage（トークン使用量）

APIを呼び出すたびに、どのくらい「言葉的力量」を消費したか記録されています。

"usage": {
  "prompt_tokens": 25,      # 入力テキスト消費量
  "completion_tokens": 150,  # 出力テキスト消費量
  "total_tokens": 175        # 合計消費量
}

【ヒント】DeepSeek V3.2は$0.42/MTokと非常に安価なので、長文処理ならHolySheep AIのDeepSeekプランがお得です。GPT-4o-miniなら$0.15/MTok、Claude Sonnet 4.5 offer就更大了。

2. x-ratelimit-* ヘッダー

HolySheep AIは以下ヘッダーを返します：

• x-ratelimit-remaining：残りリクエスト回数
• x-ratelimit-reset：レートリミットがリセットされるUNIX時刻

実践的なデバッグスクリプト

ここからは、私が実際に使っている「問題発生時にすぐ試せる」デバッグスクリプト紹介します。

import requests
import json
import time
from typing import Dict, Any, Optional

BASE_URL = "https://api.holysheep.ai/v1"

class APIDebugger:
    """API呼び出しの詳細ログとエラー処理を 담당するクラス"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.request_log = []
        self.response_log = []
        self.error_log = []
    
    def _print_section(self, title: str):
        print(f"\n{'='*60}")
        print(f" {title}")
        print(f"{'='*60}")
    
    def diagnose_error(self, response: requests.Response) -> Dict[str, Any]:
        """エラーレスポンスの詳細診断"""
        status = response.status_code
        diagnosis = {
            "status_code": status,
            "problem": "",
            "solution": "",
            "details": {}
        }
        
        try:
            error_data = response.json()
            diagnosis["details"] = error_data
        except:
            diagnosis["details"] = {"raw_text": response.text}
        
        if status == 400:
            diagnosis["problem"] = "リクエストボディの形式エラー"
            diagnosis["solution"] = "JSON構文を確認、必須フィールド(payload, modelなど)를 확인하세요"
        
        elif status == 401:
            diagnosis["problem"] = "認証エラー - APIキーが無効"
            diagnosis["solution"] = "APIキーを確認、頭に'Bearer 'を付けることを忘れない"
        
        elif status == 403:
            diagnosis["problem"] = "権限エラー - アクセス禁止"
            diagnosis["solution"] = "利用하려는modelが自分のプランで利用可能か確認"
        
        elif status == 429:
            diagnosis["problem"] = "レートリミット超過"
            reset_time = response.headers.get("x-ratelimit-reset", "不明")
            diagnosis["solution"] = f"{reset_time}まで待機してください"
        
        elif status == 500:
            diagnosis["problem"] = "サーバー内部エラー"
            diagnosis["solution"] = "数分後に再試行してください（HolySheep AIは高い安定性著称）"
        
        elif status == 503:
            diagnosis["problem"] = "サービス一時停止中"
            diagnosis["solution"] = "メンテナンス情報を確認、稍后再试"
        
        else:
            diagnosis["problem"] = "不明なエラー"
            diagnosis["solution"] = "サポート 联系してください"
        
        return diagnosis
    
    def test_connection(self, model: str = "gpt-4o-mini") -> bool:
        """API接続テストを実行"""
        self._print_section("API接続テスト")
        
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
        
        data = {
            "model": model,
            "messages": [{"role": "user", "content": "test"}],
            "max_tokens": 10
        }
        
        print(f"[REQUEST] {BASE_URL}/chat/completions")
        print(f"[MODEL] {model}")
        
        start = time.time()
        response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers=headers,
            json=data,
            timeout=10
        )
        elapsed_ms = (time.time() - start) * 1000
        
        print(f"[STATUS] {response.status_code}")
        print(f"[LATENCY] {elapsed_ms:.1f}ms")
        
        if response.status_code == 200:
            result = response.json()
            print(f"[SUCCESS] Model: {result.get('model')}")
            print(f"[USAGE] {result.get('usage')}")
            return True
        else:
            diag = self.diagnose_error(response)
            print(f"[ERROR] {diag['problem']}")
            print(f"[SOLUTION] {diag['solution']}")
            print(f"[DETAILS] {diag['details']}")
            self.error_log.append(diag)
            return False
    
    def safe_api_call(self, model: str, prompt: str, 
                      max_retries: int = 3) -> Optional[Dict]:
        """安全なAPI呼び出し（自動リトライ付き）"""
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
        
        data = {
            "model": model,
            "messages": [{"role": "user", "content": prompt}],
            "max_tokens": 1000
        }
        
        for attempt in range(max_retries):
            try:
                print(f"\n[ATTEMPT {attempt + 1}/{max_retries}]")
                response = requests.post(
                    f"{BASE_URL}/chat/completions",
                    headers=headers,
                    json=data,
                    timeout=30
                )
                
                if response.status_code == 200:
                    return response.json()
                elif response.status_code == 429:
                    print("[WAIT] レートリミット超過、5秒待機...")
                    time.sleep(5)
                    continue
                else:
                    diag = self.diagnose_error(response)
                    print(f"[FAILED] {diag['problem']}")
                    print(f"[DETAILS] {diag['details']}")
                    return None
                    
            except requests.exceptions.Timeout:
                print(f"[TIMEOUT] リクエストが30秒以内に完了しませんでした")
            except requests.exceptions.ConnectionError:
                print(f"[CONNECTION ERROR] ネットワーク接続を確認してください")
        
        print(f"[FAILED] {max_retries}回尝试しても成功しませんでした")
        return None

使用例
if __name__ == "__main__":
    debugger = APIDebugger(api_key="YOUR_HOLYSHEEP_API_KEY")
    
    # 1. 接続テスト
    debugger.test_connection()
    
    # 2. 実際のAPI呼び出し
    result = debugger.safe_api_call(
        model="gpt-4o-mini",
        prompt="美味しいチョコレートの銘柄を3つ教えて"
    )
    
    if result:
        print(f"\n[RESULT] {result['choices'][0]['message']['content']}")

よくあるエラーと対処法

エラー1：401 Unauthorized - APIキー認証失敗

【症状】{"error": {"message": "Invalid authentication", "type": "invalid_request_error"}}

【原因】APIキーが正しく送信されていない最も一般的な原因：

• Bearer プレフィックスを忘れた
• APIキーの前後に余分なスペースがある
• コピー＆ペースト時に空白が混じった

【解決コード】

# ❌ 間違い
headers = {
    "Authorization": "YOUR_HOLYSHEEP_API_KEY"  # Bearer がない！
}

✅ 正しい
headers = {
    "Authorization": f"Bearer {api_key}"
}

✅ さらに安全（空白除去）
headers = {
    "Authorization": f"Bearer {api_key.strip()}"
}

エラー2：400 Bad Request - JSON形式エラー

【症状】{"error": {"message": "Invalid JSON body", "type": "invalid_request_error"}}

【原因】PythonのdictとJSONの変換でよくある失敗：

【解決コード】

# ❌ 間違い：文字列としてJSONを送信
data = '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好"}]
}'

✅ 正しい：dictを送信（requestsが自動変換）
data = {
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好"}]
}
response = requests.post(url, headers=headers, json=data)

✅ JSONとして明示的に送信する場合
data = json.dumps({
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好"}]
})
response = requests.post(url, headers=headers, data=data)

エラー3：429 Too Many Requests - レート制限超過

【症状】{"error": {"message": "Rate limit exceeded", "type": "rate_limit_error"}}

【原因】短時間に大量のリクエストを送信し過ぎた

【解決コード】

import time
from datetime import datetime, timedelta

def rate_limited_request(api_call_func, max_calls_per_minute=60):
    """レート制限対応のラッパー"""
    min_interval = 60.0 / max_calls_per_minute
    last_call_time = 0
    
    def wrapper(*args, **kwargs):
        nonlocal last_call_time
        elapsed = time.time() - last_call_time
        
        if elapsed < min_interval:
            wait_time = min_interval - elapsed
            print(f"[RATE LIMIT] {wait_time:.2f}秒待機...")
            time.sleep(wait_time)
        
        result = api_call_func(*args, **kwargs)
        last_call_time = time.time()
        return result
    
    return wrapper

使用例
@rate_limited_request(max_calls_per_minute=30)
def call_ai(prompt):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": prompt}],
        "max_tokens": 100
    }
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=data
    )
    return response.json()

複数呼び出しも安心
for i in range(10):
    result = call_ai(f"質問{i+1}：天気について")
    print(f"回答: {result['choices'][0]['message']['content'][:50]}...")

エラー4：モデル名不正 - 503 Service Unavailable

【症状】{"error": {"message": "Model not found", "type": "invalid_request_error"}}

【原因】存在しないmodel名を指定している

【解決コード】

# 利用可能なモデルを列表して確認
def list_available_models(api_key):
    """利用可能なモデル一覧を取得"""
    headers = {
        "Authorization": f"Bearer {api_key}"
    }
    
    # models エンドポイントがある場合
    response = requests.get(
        f"{BASE_URL}/models",
        headers=headers,
        timeout=10
    )
    
    if response.status_code == 200:
        models = response.json()
        print("利用可能なモデル:")
        for model in models.get("data", []):
            print(f"  - {model['id']}")
        return models
    else:
        print("models エンドポイントは未対応")
        # よく使うmodelをハードコード
        known_models = [
            "gpt-4o",
            "gpt-4o-mini", 
            "gpt-4-turbo",
            "gpt-3.5-turbo",
            "claude-3.5-sonnet",
            "claude-3-opus",
            "gemini-1.5-pro",
            "gemini-1.5-flash",
            "deepseek-chat"
        ]
        print("よく使われるモデル:")
        for m in known_models:
            print(f"  - {m}")
        return known_models

まず利用可能なモデルを確認
available = list_available_models("YOUR_HOLYSHEEP_API_KEY")

実際のトラブルケーススタディ

ケース1：応答が突然止まった

私自身の経験ですが、batch処理中に突然エラーが频出しました。ログを見ると：

[STATUS] 200 OK
[LATENCY] 45ms
[USAGE] {"prompt_tokens": 100, "completion_tokens": 500, "total_tokens": 600}
---
[STATUS] 200 OK
[LATENCY] 1200ms  ← 急に遅くなった
[USAGE] {"prompt_tokens": 100, "completion_tokens": 500, "total_tokens": 600}
---
[STATUS] 429 Too Many Requests  ← レート制限
[ERROR] Rate limit exceeded

原因：ループ内でrequestsを連打して、レートリミットを超えた

解決：time.sleep(0.1)をループに追加して、1秒あたり10リクエスト以下に抑制

ケース2：中文が文字化けした

日本語APIに中国語を入力したら、レスポンスが\u4e2d\u6587のようなunicode-escapeで返ってきた。

# ❌ 文字化けする例
print(response.text)

✅ 文字化け解決
import json
data = json.loads(response.text)
print(data["choices"][0]["message"]["content"])

HolySheep AI でログ分析をスムーズに

HolySheep AI的最大优点是 поддержка WeChat Pay 和 Alipay，対応しているので中国大陆の开发者也能 쉽게 利用できます。而且<50msの低レイテンシ实现了快速的ログ分析。GPT-4.1が$8/MTok、Claude Sonnet 4.5が$15/MTokするのに比べて、DeepSeek V3.2は$0.42/MTokという破格の安さも魅力的です。

【ヒント】ログ分析が初めての方は、最初は1つのリクエストだけを试して、全部の項目を確認しましょう。「習うより慣れろ」が一番の近道です！

まとめ

• APIログは「ドラマの台本」— リクエストとレスポンスの記録
• ステータスコード200=成功、400番台=クライアントエラー、500番台=サーバーエラー
• rate limit (429エラー) は time.sleep()で待機すれば大抵解決
• 認証エラー (401) は Bearer プレフィックスの確認から
• HolySheep AIなら¥1=$1のレートで85%節約、<50msの高速応答

ログ分析のスキルを身に付ければ、API開発が劇的に楽になります。この記事を参考に、まずは小さなリクエストから試してみましょう！

👉 HolySheep AI に登録して無料クレジットを獲得