エラー処理 | Developer API

Fit It On APIがどのようにエラーを報告するか、APIレベルの障害と非同期ランタイムエラーを含めて理解します。

APIがエラーを報告する方法を理解することは、迅速に対応し、統合の回復力を維持するのに役立ちます。Fit It On APIは、エラーを2つの異なるフェーズに分類します。

APIレベルのエラー: 予測IDが発行される直前にリクエストが即座に拒否されました。
ランタイムエラー: リクエストは受け入れられ、予測IDが返されましたが、非同期処理中に生成が失敗しました。

APIレベルのエラー

APIレベルのエラーは同期的に発生します。/v1/runへのPOSTリクエスト、または/v1/status/{id}へのGETリクエストを行うと、サーバーは集中的なバックグラウンド作業を開始する前にリクエストを検証します。

検証が失敗した場合、APIはHTTPエラー状態（例：400、401）を返し、JSONレスポンスにはerrorメッセージと特定の文字列codeが含まれます。

{
  "error": "Invalid request payload. Expected { model_name, inputs }",
  "code": "BadRequest"
}

標準エラーコード

コード	エラー	原因	修正方法
400	BadRequest	無効なリクエスト形式またはサポートされていないモデル名	JSON構造を確認し、`model_name`が正しいことを確認し、必要な`inputs`がすべて提供されていることを確認してください。
401	UnauthorizedAccess	無効または欠落しているAPIキー	`Authorization: Bearer YOUR_API_KEY`ヘッダーが正しいこと、およびキーがアクティブであることを確認してください。
402	OutOfCredits	開発者APIクレジットが残っていません	再試行する前に、Fit It Onダッシュボードでクレジットを補充してください。
403	Forbidden	予測への不正アクセス	別の開発者キーによって作成された予測のステータスを確認しようとしています。
404	NotFound	予測が見つかりません	ステータスエンドポイントをポーリングする際に、予測IDが正しいことを確認してください。
413	PayloadTooLarge	ペイロードが制限を超えています	入力画像が25MB未満であり、適切な解像度を使用していることを確認してください。
500	InternalServerError	サーバー側のエラー	バックオフして再試行してください。問題が解決しない場合はサポートにお問い合わせください。

[!TIP] 再試行と冪等性 APIレベルのエラーが発生した場合、問題が解決されれば、まったく同じペイロードを安全に再試行できます。リクエストは即座に拒否されたため、クレジットは差し引かれず、重複処理のリスクもありません。

ランタイムエラー

ランタイムエラーは、APIがリクエストを正常に受け入れ、予測IDを返した後に発生します。

生成モデルは非常に非同期であるため、これらのエラーは/v1/status/{id}エンドポイントをポーリングしているときに発見されます。バックグラウンドジョブが失敗した場合、エンドポイントはHTTP 200 OKを返しますが（ポーリングリクエスト自体は成功したため）、ペイロード内のstatusフィールドは"failed"になります。

レスポンスには予測IDと、何が問題だったかを詳細に説明するerrorオブジェクトが含まれ、分類されたnameと説明的なmessageが含まれます。

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "output": null,
  "error": {
    "name": "ImageLoadError",
    "message": "Failed to load input image: URL returned 404"
  },
  "created_at": "2024-05-15T12:00:00Z",
  "updated_at": "2024-05-15T12:00:10Z"
}

一般的なランタイムエラー

ほとんどのランタイムの問題は、当社のモデル全体でいくつかの共通のカテゴリに分類されます。

カテゴリ	一般的なエラーメッセージ	修正方法
Image Load Error	`Failed to fetch image`、`Invalid image URL`	提供されたURLが認証なしで公開アクセス可能であることを確認してください。Base64の場合、正しいMIMEタイププレフィックスが含まれていることを確認してください。
Input Validation	`Image resolution too small`、`Missing required parameter`	入力アセットが特定のモデルの最小寸法と要件を満たしていることを確認してください。
Content Moderation	`NSFW content detected`、`Safety block triggered`	安全フィルターに準拠するように、入力画像またはテキストプロンプトを置き換えるか調整してください。
Pipeline Error	`Generation failed`、`Server error`	GPUクラスターで予期しない障害が発生しました。バックオフしてリクエストを再試行してください。

[!NOTE] 失敗時のクレジット返金 失敗した予測はクレジットを消費しません。ランタイム中に生成が失敗した場合（例：Image Load ErrorやPipeline Errorのため）、リクエスト開始時に差し引かれたクレジットは自動的に開発者残高に返金されます。

エンドポイント固有のエラー

特定のモデルには、生成中に実行される厳格なワークフロー固有の検証ルールがあります。

ポーズ制御: ターゲット画像で人間の体が検出されない場合、失敗します。
バーチャル試着: 衣服画像で有効な衣服を検出できない場合、失敗します。
モデル生成: 提供された顔参照画像に明確で遮るもののない顔が含まれていない場合、失敗します。

ドキュメントに合わせて入力を調整した後もランタイムエラーが続く場合は、予測IDを添えてサポートにお問い合わせください。調査いたします。