エラー

エラーは2つの層に分かれています。どちらも処理してください。

• HTTPステータス: 通信・認証・利用条件のエラー。ツールは実行されていません
• 業務エラー: ツールは実行され、業務上の理由で失敗したもの。応答本文の error.code に入ります

HTTPステータス

401が返るときは、エラー本文に理由の詳細は含まれません。キーの有無を外部から推測できないようにする ためです。OAuth接続では、WWW-Authenticate ヘッダーで認可の入口を案内します。

OAuthエラー

業務エラー

応答は次の形です。

{
  "ok": false,
  "error": {
    "code": "payment_required",
    "message": "クレジットが不足しています(必要60 / 残高10)",
    "required": 60,
    "balance": 10,
    "retryable": false
  }
}

漫画ショート動画: ツール応答と `get_job_status` の区別

provider_* は、非同期ジョブでは get_job_status をポーリングして errorCode / retryable を見ます。 同期処理中に外部 API が失敗した場合は、同じ code がツール応答の error.code に入ることがあります （そのとき retryable は応答本文の値に従います）。詳細は 基盤ツール `get_job_status`を参照してください。

retryable の意味

error.retryable は、同じ入力で再試行して結果が変わりうるかを示します。

• true: 時間をおいて再試行する価値がある（internal_error、実行中を示す conflict、provider_rate_limited など）
• false: 入力または前提を変えないかぎり、何度実行しても同じ結果になる（service_not_configured、audio_not_confirmed、provider_not_configured など）
• get_job_status の retryable が null のとき（漫画ショート動画の provider_request_failed など）は、1回だけ同じ入力で再試行し、再度失敗したら利用者へ報告する

通信断などで起動結果が不明な場合は、最初と同じ idempotency_key・同じ入力で再送して元の結果を確認します。 同期ツールが再試行可能な失敗を返した場合も、同じキー・同じ入力で再試行します。 一方、起動に成功した非同期ジョブの最終失敗を get_job_status で確認し、再実行するときは、 新しい冪等キー（idempotency_key）で新規実行します。起動時の成功結果は確定済みなので、 旧キーでは失敗した元のジョブが返るだけで再起動されません。再実行の可否はそのジョブの retryable に従います。 validation_error の入力を修正した場合や、更新競合の後に最新データを読み直して操作内容を変えた場合も、 新しいキーを使います。確定済みの結果に同じキーを使うと、最初の結果がそのまま返ります。 詳しくは共通仕様を参照してください。

追加のフィールド

エラーの種類によって、判断材料になるフィールドが付きます。

payment_requiredの切り分けには、まずmessageを確認してください。 「APIキーの日次クレジット上限に達しました。」なら日次上限です。この場合のrequiredは日次上限、 balanceは今回の確保対象額であり、組織の利用残高ではありません。 requiredとbalanceの大小だけで、残高不足と日次上限を判定しないでください。

無料トライアル中の組織では、ツール結果のJSONに planNotice（kind と message）が付くことがあります。 CMO AI Pro から利用者へのお知らせです（例: クレジットが足りないときの月額プランの案内、トライアル終了の予告）。 作業の区切りで利用者に伝えてください。有料プランの組織の応答には付きません。

エラーメッセージに含まれないもの

安全のため、エラー応答には次を含めません。ログにも出力されません。

• APIキー
• 生成プロンプトの本文
• 画像の署名URL
• 他組織のデータの有無

このため、別組織のIDを指定した場合と、実在しないIDを指定した場合は、どちらも同じ not_found に なります。