HappyOyster Open API 回應結構與錯誤碼說明，包括業務碼、典型場景與處理建議。
本文說明 HappyOyster Open API 的回應結構和錯誤碼，適用於 Adventure、Directing、Acting 三個模型的全部 Open API 介面。
回應結構
請求通過網關鑑權後（含業務成功與業務錯誤），回應統一返回 HTTP 200，Body 為如下 JSON 結構體：
{
"code": 0,
"message": null,
"data": {}
}
| 欄位 | 類型 | 說明 |
|---|---|---|
code | integer | 業務返回碼。0 表示成功，非 0 表示業務錯誤，詳見下文錯誤碼列表。 |
message | string | null | 可讀的錯誤訊息；code=0 時為 null。 |
data | object | null | 業務資料。成功時為對應介面的返回物件；錯誤時通常為 null。 |
閘道器層的 AK、簽名、時間戳記等驗證失敗會直接被攔截，回應不遵循該結構，通常以 4xx / 5xx HTTP 狀態碼返回，詳見錯誤碼。
錯誤碼列表
| code | 說明 | 典型場景與處理建議 |
|---|---|---|
0 | 成功 | 請求成功，讀取 data。 |
400000 | 請求參數無效 | mode 與當前模型不符；prompt 或 firstFrameImage 缺失；prompt 超長；creationModel / uploadMode / resolution / aspectRatio / perspective 等取值非法；圖片或加密 ID 格式錯誤。按介面文件校正入參後重試。 |
400001 | 圖片 URL 拉取或轉存失敗 | 首幀圖或參考圖 URL 不可存取或已過期。檢查 URL 可存取性與有效期後重試建立 World。 |
401010 | ticket 無效或已過期 | 進房（enter-travel）。重新呼叫獲取體驗憑證換取新 ticket。 |
401011 | ticket 已使用 | 進房。ticket 為一次性憑證，需重新換取。 |
403001 | World 不存在、已刪除、不歸屬或不屬於當前模型 | 查詢、換憑證、進房與列表篩選。刪除時僅跨帳號、workspace 或跨模型 ID 返回該碼；同帳號下已不存在的 ID 返回 code=0, deleted=false。 |
403002 | World 不是 ready 或不可用 | 換憑證、進房。先輪詢建構狀態至 ready 再操作。 |
403003 | 當前介面僅允許主 API Key | World 管理、Travel 列表、產物等介面。改用主 API Key（sk- 開頭）呼叫。 |
403004 | 輸入內容未通過內容安全策略 | 建立 World、發送 instruct。調整文字內容後重試。 |
403005 | 輸入圖片版權或 IP 校驗不通過 | 建立 World。更換合規圖片後重試。 |
403007 | 功能或服務規格未開通 | 建立、換憑證、進房。確認已開通對應模型能力。 |
403008 | 容量配置暫不可用 | 建立、換憑證、進房。稍後重試或聯絡服務方擴容。 |
404000 | Travel 不存在、不歸屬、不屬於當前模型或無可用產物 | Travel 狀態查詢、控制、結束、產物查詢。 |
409000 | 請求與目前資源狀態衝突 | 暫停、恢復、結束、指令等控制介面；對不支援該介面的模型呼叫同樣返回。 |
429001 | 目前規格併發已滿 | 進房。稍後重試或提升並行規格。 |
429002 | 目前可用容量不足 | 進房。稍後重試。 |
500000 | 系統內部錯誤 | 未分類異常；對不支援的介面（如部分模型的 rewind）呼叫也可能返回。 |
500001 | 推流資源分配失敗 | 進房。稍後重試。 |
跨模型存取不洩露資源是否存在，World 統一返回 code=403001，Travel 統一返回 code=404000。
Travel 失敗 errorCode
查詢 Travel 狀態或清單時，status=failed 的條目會額外返回結構化欄位 errorCode 與英文說明 errorMessage（失敗回應結構見對應介面文件）。同一 errorCode 在查詢介面和結束 Travel 回應中的 errorMessage 文案可能不同；請按 errorCode 分支處理，不要匹配 errorMessage。
| errorCode | errorMessage | 說明 |
|---|---|---|
TRAVEL_SESSION_INIT_FAILED | Failed to allocate inference resources. | 進房時推理工作階段初始化失敗，多為推理資源不足 |
TRAVEL_NO_STREAM_AUTO_END | No video stream was received before timeout. | 客戶端逾時未收到推流，透過結束 Travel 傳入 failCode 結束 |
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 按未知失敗處理即可。