エラーと再試行

エラーとリクエスト ID で調査。

HTTP 429 はローカルの受付負荷、キュー満杯、上流の制限で発生する場合があります。エラーと Retry-After を確認してください。RPM や TPM が無制限という意味ではありません。

Retry-After を守り、ジッター付き指数バックオフで回数と合計時間を制限してください。動画ジョブが作成済みの可能性がある場合は、再送前に ID で照会してください。

x-apivn-request-id があればエラー時刻とともに保存してください。報告に API キーや機密データを含めないでください。

エラーコード

HTTP	エラーの種類	原因
400	invalid_request_error	JSONが不正、またはパラメータ不足
401	authentication_error	キーが未設定、不正、または失効済み
402	insufficient_balance api_key_monthly_limit outstanding_undercharge	error.type を確認してください。insufficient_balance は利用可能残高不足、api_key_monthly_limit はキーの月間支出上限到達、outstanding_undercharge は以前のリクエストの未精算額を示します。キーの上限は Dashboard → Keys で確認してください。ウォレットへの入金で上限が自動的に増えることはありません。
403	model_not_allowed	この API キーには選択したモデルの使用権限がありません。Dashboard → Keys でモデルの権限を確認するか、許可されたモデルを選択してください。
413	request_too_large	本文が 20 MB を超えているか、入力がモデル・プロバイダー固有の制限を超えています。メッセージを読み、コンテキスト、画像、ファイルを減らしてください。ゲートウェイの上限未満でも 413 になる場合があります。
429	rate_limit_error	HTTP 429 はローカルの受付負荷、キュー満杯、上流の制限で発生する場合があります。エラーと Retry-After を確認してください。RPM や TPM が無制限という意味ではありません。
502	api_error	上流プロバイダーのモデルに接続できません
503	service_unavailable	システムはメンテナンス中です

残高エラーには required_vnd と available_vnd、キー上限エラーには limit_vnd と spent_vnd が含まれる場合があります。調査のため request ID とともに保存し、API キーは共有しないでください。

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "残高を使い切りました。https://apivn.dev/dashboard/topup からチャージしてください"
  }
}

トラブルシューティング

料金ページでモデルの状態を見る

x-apivn-request-id があればエラー時刻とともに保存してください。報告に API キーや機密データを含めないでください。

症状	よくある原因	対処方法
404 または「Not Found」	ベースURLの貼り付けが正しくありません — /v1 が余分にあるか、不足しています。	Anthropicスタイルのツールには https://apivn.dev を、OpenAIスタイルのツールには https://apivn.dev/v1 を使用します。
401 authentication_error	キーが間違っている、取り消されている、またはアプリが保存済みの古いキーを使い続けています。	ダッシュボードで新しいキーを作成し、アプリ内の古いキーを削除してから、アプリを再起動してください。
402 insufficient_balance	ウォレットの残高がなくなりました。	チャージページから追加チャージしてください。
429 rate_limit_error	HTTP 429 はローカルの受付負荷、キュー満杯、上流の制限で発生する場合があります。エラーと Retry-After を確認してください。RPM や TPM が無制限という意味ではありません。	Retry-After を守り、ジッター付き指数バックオフで回数と合計時間を制限してください。動画ジョブが作成済みの可能性がある場合は、再送前に ID で照会してください。
Claude Codeがログインを求め続ける	マシンに古いAnthropicアカウントのログインセッションが残っています。	Claude Codeで /logout を実行し、ANTHROPIC_AUTH_TOKEN を設定してからターミナルを開き直してください。
アプリがモデルが存在しないと表示する	モデル名の入力ミス、またはアプリがプロバイダーのプレフィックスを自動的に付加している可能性があります。	GET /v1/models を呼び出して正しい名前を取得し、アプリが要求しない場合は anthropic/ などのプレフィックスを削除してください。
画像を送信するとエラーになる	アプリがそのモデルが受け付けない形式で画像を送信しているか、画像が大きすぎます。	Chỉ dùng model có nhãn Vision, nén ảnh và giữ toàn bộ yêu cầu dưới 20 MB.
環境変数が反映されない	古いターミナルが以前の値を保持しているか、アプリが別ファイルから設定を読み込んでいる可能性があります。	新しいターミナルを開き（Windowsの場合はログアウト／ログインし直してください）、アプリに環境変数を上書きする設定ファイルがないか確認してください。

例はソース確認とローカル検証の対象であり、全アプリバージョンの実機検証を意味しません。実運用前に設定、小さなリクエスト、使用量を確認してください。