エラー

2xx 以外のすべてのレスポンスは、同じ OpenAI 標準の JSON 形式です。プログラムで処理する場合は error.code を、再試行ポリシーには status_code を基準にしてください。

エラーペイロード

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

HTTP ステータスコード

よくあるエラーコード

authentication_error

• Authorization: Bearer ... ヘッダーの設定忘れ。
• API キーが /app/keys から失効されました。
• キーのプレフィックスがまだ間違っています（sk-kn- で始まる必要があります）。

insufficient_quota

• ウォレット残高がこのリクエストに足りません → error.code は insufficient_balance で、エラーにはウォレットにあった残高（balance_usd）、このリクエストで確保される額（needed_usd）、2つのリンクが含まれます。topup_url はチャージがあらかじめ選択された状態で課金ページを開き、auto_recharge_url は課金ページの自動チャージ設定を開きます。どちらのリンクも、それ自体で課金を行うことはありません。
• キーごとの月間上限に達しました。上限は UTC の暦月初めにリセットされます。/app/keys で上限を引き上げてください。

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing — or turn on auto-recharge there, and a saved card refills the wallet before requests are refused.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

レスポンスに Retry-After ヘッダーがない限り、insufficient_balance の再試行は停止してください。このヘッダーは自動チャージが保存済みのカードに対してすでに処理中であることを示し、数秒後には同じリクエストが成功することを意味します。

permission_error

• キーには IP 許可リストが設定されており、呼び出し元のアドレスがリスト外でした。メッセージには検出されたアドレスが示されます。/app/keys でそのアドレス（または CIDR ブロック）を追加するか、許可リストを完全に削除してすべてのアドレスを許可してください。
• エージェントを新しいホスト、新しい NAT ゲートウェイ、または別のネットワーク上のノート PC に移すと、そのアドレスも変わります。許可リストを設定していないキーが、この理由で拒否されることはありません。

model_not_found

• スラッグの誤記です。正規の一覧は /models を使用してください。
• モデルは現在無効になっています（上流の障害または料金の確認中）。

upstream_error

上流のモデルプロバイダーがエラーを返し、より具体的なコードに変換できなかったことを示します。本文には元のメッセージが含まれます。一般的な原因：

• プロバイダー側の過負荷。
• コンテンツモデレーションによる拒否（別のプロンプトをお試しください）。
• 地域または利用可否の制限。

再試行の戦略

最もシンプルで堅牢な方法は、429 / 5xx の場合に限ってジッターを加えた指数バックオフを行うことです。

import time, random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• 1 回の試行につき待機時間は最大 30 秒、合計は 5 回の試行までにします。
• 408 と 429 を除き、4xx は再試行しないでください。再試行しても時間を浪費するだけです。
• 画像生成と動画生成は冪等ではありません。再試行は新たな生成となり、成功すれば課金されます。失敗した呼び出しは課金されていないため、その再試行は安全です。動画ではPOST /v1/videosがIdempotency-Keyヘッダーに対応しており、同じキーで再送信すると最初のタスクが返されます。
• 独自コードで副作用を伴うチャットを行う場合は、アプリケーション層で冪等性キーを使って重複を排除してください。

ダッシュボードでのデバッグ

成功・失敗を問わず、すべての API 呼び出しは /app/usage で確認できます。任意の行をクリックすると、リクエストとレスポンスの詳細ページが開きます。

• クライアントに返された HTTP ステータスコード。
• 該当する場合は上流のエラーコード。
• レイテンシ、リクエスト IP、ユーザーエージェント。
• ステータスで絞り込むと、傾向を把握しやすくなります（例：特定のモデルで発生したすべての 422 エラー）。

インシデントの報告

正常に動作するはずのモデルで 5xx が継続して発生する場合は、以下を添えて support@kunavo.com までメールでご連絡ください。

• モデルのスラッグとリクエスト本文のサンプル（秘密情報は削除してください）。
• 障害が発生した時間帯。
• レスポンスに含まれるエラー code + message。
• 可能であれば、/app/usage/[id] の使用ログへのリンク。

1 営業日以内に返信します。緊急で売上に影響する問題には、より迅速に返信します。

次に確認する項目

• 請求が 402 / クォータエラーに与える影響
• API キーの管理