トラブルシューティングと復旧

受付結果が不明なリクエスト、見積もりの競合、アップロード、ストリームの問題を調べます。

調査に必要な情報を残す

時刻、API、HTTP ステータス、業務 code、request_id、取得済みの taskId を記録します。明示的な拒否、応答を受信できなかった状態、受付後の失敗を区別してください。API キー、プロンプト全文、元ファイルを一般ログや問い合わせに添付しないでください。

モデルが見つからない・利用できない

認証済みカタログを更新し、enabled、available、正確なタスクモデル ID を確認します。公開モデルページの存在だけでは利用権限を判断できません。50301 が続く場合は利用可否を再確認し、再試行回数を制限します。未公開モデルは再試行しても利用可能になりません。

入力エラー・見積もりの競合

400 では最新の inputSchema の型、列挙値、条件付き必須項目を確認し、未対応の項目を削除します。40901 では入力、期限、料金を確認して再見積もりと承認を行います。通常の 409 は操作別に判断します。異なる入力に使ったキーの競合は業務上の対応付けを修正してください。

タスク ID を受信する前にタイムアウトした

元の入力と Idempotency-Key を保持し、有効期間内に同じ送信を復旧してから新規送信を判断します。taskId を取得したら recordInfo を確認します。タイムアウト、タブを閉じる操作、切断は受理済みタスクを取り消しません。state、cost、settled で結果を確認してください。

PUT は成功したのにファイルを使えない

PUT の後に files/{fileId}/commit が必要です。返された spicy:// URI をモデルが対応する入力欄に渡し、uploadUrl は渡しません。署名時の Content-Type、サイズ、形式、所有アカウント、期限を確認します。アップロードの保存期間は 1 日です。再試行時に再アップロードと入力変更が必要になる場合があります。

通知が届かない・ダウンロードできない

HTTPS の受信先、元のバイト列による署名検証、速やかな成功応答を確認します。recordInfo で状態を補い、重複通知で処理を二重実行しないでください。成果物が保存中なら期限切れ URL を再発行できます。pending は待って再試行し、unavailable や保存期限切れは古い URL の更新では復元できません。

ストリームが途中で終わる

HTTP ステータスと Content-Type を確認してから、選択したプロトコルの SSE を解析します。TCP の断片はイベントではなく、接続終了は成功の印でもありません。終了イベント、エラー、アプリの期限を確認します。切断後の返金や無料再送を仮定せず、request_id と利用履歴を確認してください。

残高・上限・問い合わせ

40201 は利用可能残高、40202 はアカウントとキーの支出上限を確認します。429 は Retry-After に従い送信頻度を下げます。問い合わせにはキーを送らず、手順、時刻、リクエスト ID、機密値を除いた入力構造、期待値と実際の結果を記載してください。