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

以下の各セクションは、目に見えている症状から始まり、よくある原因と、あなたがすべきことを説明します。エラー番号それぞれの正確な意味はエラーにまとめています。このページは、そのうえで「では、どうすればいいのか」に答えるためのページです。

症状から探す

役に立つ記録を残す

何かを変える前に、何が起きたかを書き留めてください。以下のどの手順も速く進められるようになりますし、サポートが必要とするのもこの情報です。

• 時刻。できれば UTC で書きます。
• 呼び出したエンドポイント。たとえば POST /api/v1/jobs/createTask です。
• HTTP ステータスと、応答本文の code。
• request_id。応答本文と、応答ヘッダーの X-Request-Id の両方に入っています。
• タスク ID（受け取っている場合）。job_ で始まり、コンソールのログページにも表示されます。

次の 3 つの状況は、とるべき行動が違うので、分けて考えてください。

• API がリクエストをはっきり拒否した。JSON のエラーが返っていて、何も作成されず、課金もされていません。
• 応答がまったくなかった。タイムアウトや接続切れのことで、タスクが作成されている可能性があります。後述の手順に従ってください。
• タスクが受理されたあとで失敗した。state: "failed" のタスク ID が手元にあります。

応答が JSON ではない場合（たとえば HTML やプレーンテキストのページ）、それは API に届く前に、当社のエッジネットワークが返したものです。HTTP ステータスと、本文の最初の数行を控えてください。この種類の 403 のページは、たいてい、当社がサービスを提供できない地域からリクエストが送られていることを意味します。再試行しても結果は変わりません。

API キー、パスワード、プロンプトの全文、元のファイルは、一般的なログにもサポートへの問い合わせにも、決して含めないでください。

支払ったのに残高が変わらない

• カード： 残高が変わるのは、決済事業者からの確認が当社に届いてからで、通常は数秒以内です。請求ページを再読み込みし、チャージ注文を確認してください。
• 暗号資産： ネットワークが取引を承認したあとで残高に加算されます。通常は数分です。表示された金額より少なく支払った場合や、支払いページの期限が切れたあとで支払った場合は、自動では加算されません。
• 手動送金： チャージ注文でその注文を開き、銀行の参照番号かトランザクションハッシュを送信してください。当社が手作業で確認し、通常は数時間以内に終わります。

すべてのケースはアカウントの準備 → よくある問題にまとめています。それでも反映されない場合は、注文 ID と、暗号資産の場合はトランザクションハッシュを添えて、サポートで会話（トピックは請求）を始めてください。カード番号やパスワードは絶対に送らないでください。

どの呼び出しも 401 か 403 になる

まずは、無料で何も変更しない呼び出し、つまり残高の読み取りから試します。

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

1 行目には sk-spicy- と表示されるはずです。何も表示されない場合は、このターミナルにキーが読み込まれていません。もう一度設定してください（アカウントの準備を参照）。そのうえで、応答の msg を読みます。

どれも、再試行して良くなることはありません。

残高・上限・サポート

• 40201：利用可能残高が、タスクの見積額に足りません。チャージしてから（アカウントの準備を参照）、同じ Idempotency-Key を付けて同じリクエストをもう一度送ってください。キャンペーンの付与残高で支払えるのは、その付与の対象になっているモデルだけです。
• 40202：利用上限に達しました。どの上限かは msg に書かれています。キーの上限（This key has reached its …）は、API キー → 編集で引き上げるか、自動でリセットされるのを待ちます（日次は 00:00 UTC、月次は毎月 1 日、累計はリセットされません）。チームの上限（Workspace … budget has been reached）は、オーナー、管理者、予算管理者のいずれかがチームページで引き上げます。プラットフォームの上限（Platform quota for today is exhausted…）は引き上げられないので、00:00 UTC を過ぎてから再試行してください。課金の利用上限の説明を参照してください。
• 429：リクエストが多すぎます。Retry-After に示された秒数だけ待ち、ペースを落としてください。いちばん効果があるのは、短い間隔で問い合わせ続けるループをやめて、Webhook を使うことです。メッセージが Too many pending uploads… の場合は、待っても解決しません。すでに始めたアップロードを最後まで終わらせてください。レート制限を参照してください。

サポートへの問い合わせ： コンソールのサポートで会話を始めるか、support@spicyapi.ai にメールしてください。その際、上で挙げた記録を添えてください。時刻、エンドポイント、code、request_id またはタスク ID、期待していたことと実際に起きたこと、そして非公開の値を取り除いたリクエストの構造です。API キーは絶対に送らないでください。

モデルが見つからない・使えない

• 一覧にモデルがない、または 404 が返る： API キーを付けて GET /api/v1/models を呼び出し、enabled と available がどちらも true のモデルを選んで、その ID を正確にコピーしてください。Web サイトにモデルページがあっても、あなたのキーがいまそのモデルを呼び出せることの証明にはなりません。モデルを参照してください。
• 50301：モデルがいまタスクを受け付けられません。間隔を少しずつ延ばしながら数回再試行し、それでもだめならやめてください。何度リクエストしても、使えない状態のモデルが使えるようになることはありません。カタログを取得し直し、別のモデルに切り替える前には、支払う人に確認してください。
• 40004：モデルは動いていますが、この設定の組み合わせには対応していません。msg のかっこ内に、問題になっている設定の名前が書かれています。再試行するのではなく、その値（たとえば解像度やアスペクト比）を変えてください。
• 40301：モデルは存在しますが、このキーには使用が許可されていません。キーの利用可能モデルを編集してください。

入力が不正、または見積もりと一致しない

• 400：input を、カタログにあるそのモデルの現在の inputSchema と見比べてください。見るのは、フィールド名、型、許可される値、条件付きの必須項目です。モデルの一覧に載っていないフィールドは削除します。モデルごとにスキーマが違うので、モデルを切り替えたらもう一度確認してください。
• 40003：アップロードしたファイルが、アップロード URL を発行したときに申告した内容と一致しません。正しい contentType とサイズで新しいアップロード URL を発行し、もう一度アップロードしてください。
• 413：リクエスト本文が大きすぎます。メディアは本文に埋め込まず、メディアで説明しているアップロードの手順で渡してください。
• 40901：見積もりの期限が切れた、見積もりのあとでリクエストが変わった、価格が変わった、のいずれかです。新しい見積もりを取り、新しい金額を支払う人に見せて、もう一度確認を得てください。見積もりを参照してください。
• その他の 409：操作に応じて対処します。別の内容のリクエストですでに使った冪等キーの場合、新しいリクエストには新しい正しい Idempotency-Key が必要です。同じまま再試行を繰り返しても解決しません。エラーの、409 を再試行してよい場合についての説明を参照してください。

送信がタイムアウトしてタスク ID がない

タイムアウトしても、タスクが作成されたかどうかはわかりません。新しいキーを付けて、ただ送り直すことはしないでください。2 件目のタスクが作られ、2 回課金されるおそれがあります。

クライアント側のタイムアウトも、ブラウザーのタブを閉じることも、ストリームの切断も、受理されたタスクをキャンセルしません。そもそも、受理されたタスクはキャンセルできません。

タスクが失敗した

失敗・期限切れのタスクでは通常、仮押さえ額が全額解放されます。ただし、モデルページに明記された一部のコンテンツ拒否は、受理時の見積額で課金されます。最終請求額は settled と cost で確認してください。

• そのまま再試行しない： invalid_request、unsupported_combination、content_rejected（選んだモデルがその内容を断りました。プロンプトかモデルを変えてください）。
• 少し待ってから再試行する価値がある： rate_limited、upstream_unavailable、upstream_failed。
• 先に原因を直す： invalid_asset（ファイルをもう一度アップロードする）、timeout（短い長さや低い解像度を試す）、generation_failed（同じ入力では、たいてい同じように失敗します）。

errorMessage は、人が読むための理由の説明で、モデル自身が返した英語の理由がそのまま入ることもあります。コードの分岐には errorCode だけを使ってください。コードの一覧表は、エラーのタスク失敗コードの説明にあります。再試行は新しいタスクなので、成功すればもう一度課金されます。

タスクが queued や running のまま進まない

生成には時間がかかります。長い動画なら数分かかることもあります。どのタスクにもサーバー側の締め切りがあり、recordInfo の deadlineAt として返されます。

• deadlineAt より前： コールバックを待ち続けるか、間隔を少しずつ延ばしながら recordInfo をポーリングしてください（毎秒問い合わせるのは避けます）。
• 締め切りを過ぎたあと： タスクは自動的に expired で終わって errorCode: "timeout" が付き、仮押さえされた金額は全額戻ります。何かをキャンセルする必要はありません。受理されたタスクは、そもそもキャンセルできません。

deadlineAt を大きく過ぎても running のままのタスクがあれば、タスク ID を添えてサポートに連絡してください。

アップロードは成功したのに入力が拒否される

• 確定（commit）を飛ばしている。 ファイルの PUT が成功しただけでは足りません。files/{fileId}/commit を呼び出し、返ってきた spicy:// URI をモデルの入力フィールドに渡してください。uploadUrl そのものを渡してはいけません。
• ファイルがチケットと一致しない。 申告した Content-Type、サイズ、形式を確認してください。一致しないと 40003 が返ります。
• 期限が切れている。 アップロードしたファイルは、commit の応答にある expiresAt まで使えます。既定では 1 日ですが、タスクが終わった時点でアップロードを削除する設定のアカウントでは、それより早く使えなくなります。そのため、タスクを再試行するときには、ファイルをアップロードし直す必要が出ることがあります。
• 別のアカウントのファイルである。 spicy:// URI は、それをアップロードしたアカウントのキーでしか使えません。

アップロードの手順全体は、メディアを参照してください。

コールバックが届かない・ダウンロードの期限が切れた

コールバックが届かない場合：

1. callBackUrl が、インターネットから到達できる https:// のアドレスになっているかを確認してください。暗号化されていない http:// のアドレスは受け付けません。
2. 受信側が、JSON として解析するよりも前に、受け取ったリクエストのバイト列そのものに対して署名を検証し、すぐに 2xx を返しているかを確認してください。時間のかかる処理は、自分のキューに回します。最近署名キーをローテーションした場合は、受信側で新しいキーを使う必要があります。新旧のキーを併用できる期間はありません。Webhook の署名キーについての説明を参照してください。
3. コンソールの Webhook ページで配信履歴を確認します。そこから配信を再送することもできます。
4. その間は、recordInfo でタスクを読み取ってください。ポーリングは、いつでも使える代わりの手段です。Webhook を参照してください。

コールバックは、2 回以上届いたり、遅れて届いたりすることがあります。注文の処理を完了させる前に、重複を取り除いてください。

ダウンロードリンクやファイルがなくなった場合：

• ダウンロードリンクの有効期間は 20 分です。結果がまだ保存されていれば、新しいリンクを取得するだけで済みます。古いリンクを読み込み直しても、使えるようにはなりません。
• 出力がまだストレージにコピーされている途中なら、数秒待ってからもう一度照会してください。
• 結果が保存されるのは最長で約 14 日で、アカウントでそれより短い保存期間を設定していれば、その期間になります。contentState が expired か purged になったファイルは、元に戻せません。モデルをもう一度実行してください。データ保存と破棄を参照してください。

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

使っているプロトコルの形式でストリームを解析する前に、HTTP ステータスと Content-Type を確認してください。ネットワークから届くデータのかたまりは、完全なイベントとは限りません。また、接続が閉じたことは成功の印ではありません。プロトコルが決めている最後のイベント、エラーイベントの有無、そして自分のアプリケーションで決めた締め切りを確認してください。切断されたストリームは無料だった、あるいは費用をかけずに送り直せる、とは考えないでください。切断より前に記録された有効な使用量は、課金されることがあります。request_id を控えて、利用記録を確認してください。テキストとストリーミングを参照してください。

チームの権限

• キーを作成できない。 コンソールの左サイドバーのいちばん上にある範囲の切り替えメニューで、あなたのロールが予算管理者か閲覧のみになっているチームが選ばれています。キーを作成するには、オーナー、管理者、開発者のいずれかのロールが必要です。個人の範囲に切り替えるか、チームの管理者に開発者のロールを依頼してください。
• タスクは見えるのに、プロンプトや結果が見えない。 予算管理者と閲覧のみのメンバーに見えるのは、状態、料金、利用量だけです。
• 招待を承諾できない。 招待が送られたのとまったく同じメールアドレスでサインインしてください。招待の有効期間は 7 日です。期限が切れていたら、新しい招待を依頼してください。
• チームのキーが 40201 で止まった。 チームのキーはチームのオーナーの残高を使うので、オーナーがチャージする必要があります。

ロールとチームの制限については、コンソールとチームを参照してください。

請求書を発行できない

• 請求先情報が足りない。 請求書には、宛名（会社名または個人名）、住所 1 行目、市区町村、国が必要です。これらは請求 → 請求書のいちばん上で、一度だけ入力します。
• 印字できない文字がある。 請求書に載せられるのは、ラテン文字、ギリシャ文字、キリル文字だけです。日本語や韓国語の会社名は、登記されているローマ字表記で入力してください。
• すでに発行されている。 支払い済みのチャージ 1 件ごと、締めの終わった月 1 か月ごとに、発行できるのは 1 回だけです。発行済みの書類をダウンロードしてください。内容を訂正するには、その請求書で再発行を選びます。
• その月が選べない。 利用明細を発行できるのは、すでに終わっていて、かつ利用があった月だけです。

課金の、請求書と利用明細についての説明を参照してください。

関連する手順

エラー · 本番環境への組み込み · 冪等性 · メディア · Webhook · テキストとストリーミング · アカウントの準備