HappyOyster Open API のレスポンス構造とエラーコード。ビジネスコード、代表的なシナリオ、および対処方法を含みます。
本ドキュメントでは、HappyOyster Open APIのレスポンス構造とエラーコードについて説明します。これはAdventure、Directing、およびActingモデルのすべてのOpen APIエンドポイントに適用されます。
レスポンス構造
リクエストがゲートウェイ認証を通過すると（ビジネス上の成功およびエラーの両方において）、レスポンスは常にHTTP 200を返し、ボディとして以下のJSON構造を含みます：
{
"code": 0,
"message": null,
"data": {}
}
| フィールド | 型 | 説明 |
|---|---|---|
code | integer | ビジネスリターンコード。 0 は成功を意味し、ゼロ以外の0 値はビジネスエラーを意味します。以下のエラーコードリストを参照してください。 |
message | string | null | 人間が読める形式のエラーメッセージ。 null の場合 code=0. |
data | object | null | ビジネスペイロード。成功時はエンドポイント固有のレスポンスオブジェクトが含まれ、エラー時は通常 null. |
AK、署名、またはタイムスタンプ検証などのゲートウェイ層の障害は直接拒否されるため、それらのレスポンスはこの構造に従わず、通常は4xx / 5xx HTTPステータスコードで返されます。エラーコードを参照してください。
エラーコード一覧
| code | 説明 | 代表的なシナリオと対処方法 |
|---|---|---|
0 | Success | リクエスト成功。`data` を読み取ってください。 data. |
400000 | 無効なリクエストパラメータ | mode が現在のモデルと一致しません。 prompt または firstFrameImage が不足しています。 prompt が長すぎます。 creationModel / uploadMode / resolution / aspectRatio / perspective に不正な値があります。画像または暗号化 ID の形式が無効です。API ドキュメントに従ってパラメータを修正し、再試行してください。 |
400001 | 画像 URL の取得または保存に失敗しました | 最初のフレームまたは参照画像のURLにアクセスできないか、有効期限が切れています。URLのアクセシビリティと有効性を確認してから、Worldの作成を再試行してください。 |
401010 | ticket 無効または有効期限切れ | Travel に入ります（enter-travel）。get-travel-credential を再度呼び出して新しい ticket. |
401011 | ticket は使用済みです | Travel に入ります。この ticket は使い捨てです。新しいものを取得してください。 |
403001 | Worldが存在しない、削除された、あなたに属していない、または現在のモデルに属していない | クエリ、認証情報の交換、Travelへの参加、およびリストのフィルタリング。削除時、このコードはクロスアカウント、クロスワークスペース、またはクロスモデルIDの場合にのみ返されます。同じアカウント下のすでに存在しないIDの場合は、次が返されます： code=0, deleted=false. |
403002 | World が ready または利用不可 | 認証情報の交換、Travel への参加。操作前にビルドステータスが ready になるまでポーリングしてください。 |
403003 | このエンドポイントはプライマリ API Key のみを許可します | World 管理、Travel リスト、アーティファクトなど。プライマリ API Key（`sk-` で始まる）を使用して呼び出してください。 sk-). |
403004 | 入力コンテンツがコンテンツ安全ポリシーに違反しました | World の作成、`instruct` の送信。 instructテキストコンテンツを調整して再試行してください。 |
403005 | 入力画像が著作権または IP 検証に失敗しました | World を作成します。準拠した画像に差し替えて再試行してください。 |
403007 | 機能またはサービスのクォータが有効化されていない | 作成、認証情報の交換、Travel への参加。対応するモデル機能が有効であることを Confirm してください。 |
403008 | キャパシティ設定が一時的に利用できません | 作成、認証情報の交換、Travelへの参加。後でもう一度お試しいただくか、サービスプロバイダーに連絡してスケールアップしてください。 |
404000 | Travelが存在しない、あなたに属していない、現在のモデルに属していない、または利用可能なアーティファクトがない | Travel ステータスの照会、制御、終了、アーティファクトの照会。 |
409000 | リクエストが現在のリソース状態と競合しています | 一時停止、再開、終了、指示などの制御エンドポイント。また、モデルがサポートしていないエンドポイントを呼び出した場合にも返されます。 |
429001 | 現在の仕様の同時実行数が上限に達しています | Travelへの参加。後でもう一度お試しいただくか、同時実行スペックを引き上げてください。 |
429002 | 利用可能なキャパシティが不足しています | Travel に入ります。後ほど再試行してください。 |
500000 | 内部システムエラー | 未分類の例外。サポートされていないエンドポイントを呼び出した場合にも返される可能性があります（例： rewind 一部のモデルでの `rewind`）。 |
500001 | ストリーミングリソースの割り当てに失敗しました | Travel に入ります。後ほど再試行してください。 |
クロスモデルアクセスではリソースが存在するかどうかは開示されません。Worldエンドポイントはcode=403001を返し、Travelエンドポイントはcode=404000を返します。
Travel障害errorCode
Travel ステータスまたは Travel リストを照会する際、status=failed の項目には追加で構造化フィールド errorCode と英語の説明 errorMessage が含まれます（失敗時のレスポンス構造については対応する API ドキュメントを参照してください）。同じ errorCode に対する errorMessage テキストは、クエリエンドポイントと End Travel レスポンスで異なる場合があります。分岐処理を行う際は errorMessage ではなく errorCode を基準にしてください。
| errorCode | errorMessage | 説明 |
|---|---|---|
TRAVEL_SESSION_INIT_FAILED | Failed to allocate inference resources. | Travel への参加時に推論セッションの初期化に失敗しました。通常は推論リソースの不足が原因です |
TRAVEL_NO_STREAM_AUTO_END | No video stream was received before timeout. | タイムアウト前にクライアントがストリームを受信できませんでした。End Travel リクエストで failCode を渡して Travel を終了してください |
TRAVEL_STREAM_CREATE_FAILED | Failed to create the video stream. | ストリーミングチャネルの作成に失敗しました |
CONTENT_VIDEO_MODERATION_REJECTED | Something went wrong. | 体験画面がコンテンツ安全ポリシーによって中断されました |
TRAVEL_RUNTIME_FAILED | The experience was interrupted by a runtime error. | その他のランタイム障害、またはサーバーが特定の理由を記録しませんでした |
一覧に記載されていないerrorCodeはすべて、不明な障害として扱うことができます。