文件

API v2 錯誤參考

彙整 API v2 所宣告的每個錯誤碼、HTTP 狀態碼與正式環境觸發條件。

API v2 錯誤使用結構化的 error 物件：

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

部分驗證錯誤還會包含選填的 details 欄位，提供欄位層級的資訊：

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body",
    "details": {
      "fieldErrors": {
        "message": ["Too small: expected string to have >=1 characters"]
      }
    }
  }
}

每個 v2 回應都包含 x-request-id 標頭。聯絡支援團隊時請附上此值。請針對 error.code 編寫程式邏輯；訊息與驗證詳情僅提供人類可讀的參考資訊。

錯誤目錄

下表列出 API v2 所宣告的全部 30 個代碼。標示為「—」代表該代碼已保留但尚無正式環境呼叫端使用，因此目前未定義 HTTP 狀態碼或觸發條件。

代碼HTTP 狀態碼觸發時機備註
VALIDATION_INVALID_BODY400請求主體、路徑值、查詢值、limit、cursor、對話來源、來源類型或來源處理輸入未通過驗證。只有在呼叫端有提供時，才會包含 details。
VALIDATION_INVALID_JSON400聊天、重試、工具結果或意見回饋端點收到非合法 JSON 的請求主體。其他管理端點會將格式錯誤的 JSON 視為無效主體處理。
AUTH_MISSING_API_KEY401需要驗證的端點未收到 Authorization 標頭，或該值不是以 Bearer 開頭。健康檢查端點不需要驗證。
AUTH_INVALID_API_KEY401無法驗證此 Bearer API 金鑰。請使用有效的工作區 API 金鑰。
AUTH_EXPIRED_API_KEY—已保留；目前未由任何正式環境的 v2 路由觸發。未定義狀態碼或觸發條件。
SUBSCRIPTION_PLAN_REQUIRED403此 API 金鑰有效，但其工作區沒有 apiAccess 方案功能。使用 API 需要 Hobby 方案以上，且帳單狀態為有效。
SUBSCRIPTION_API_RESTRICTED_PLAN403呼叫端在沒有方案存取權限的情況下啟用自動重新訓練，或在沒有影片轉錄存取權限的情況下提交影片 URL。此 API 金鑰本身仍然有效。
AUTH_INSUFFICIENT_PERMISSIONS—已保留；目前未由任何正式環境的 v2 路由觸發。未定義狀態碼或觸發條件。
AGENT_NOT_FOUND404代理程式範圍的請求所指定的代理程式不存在，或不屬於此 API 金鑰所屬的帳戶。擁有權驗證失敗與代理程式不存在會回傳相同的回應。
RESOURCE_NOT_FOUND404找不到某個明細、訊息、重試或意見回饋操作所需的 API v2 對話。變更與訊息列表操作僅適用於 API v2 對話。
RESOURCE_DOCUMENT_NOT_FOUND404來源刪除操作指定的文件對該代理程式而言不存在。無效的非 UUID 文件 ID 會改回傳 VALIDATION_INVALID_BODY。
RESOURCE_MESSAGE_NOT_FOUND404意見回饋指定了無效的訊息 ID，或該訊息不在指定的 API v2 對話中。訊息 ID 是以字串序列化的正整數。
RESOURCE_MESSAGE_NOT_ASSISTANT422意見回饋鎖定的訊息不是 AI 助理訊息。使用者訊息與工具紀錄無法接收意見回饋。
RESOURCE_TOOL_CALL_NOT_FOUND404工具結果端點無法將提供的 toolCallId 與待處理的用戶端動作配對。此呼叫未知、已過期，或屬於另一個 API v2 對話。
QUOTA_CHATBOT_LIMIT403建立代理程式將超出工作區的代理程式數量上限。請刪除一個代理程式或升級方案後再試一次。
QUOTA_STORAGE_LIMIT403文字或問答（Q&A）來源處理回報儲存空間已達上限、新的 URL 無法納入可用儲存空間，或 URL 工作建立時回報配額失敗。重新訓練既有 URL 不會消耗新的文件儲存空間。
CHAT_MODEL_NOT_ALLOWED403AI 設定更新選擇了工作區方案未開放使用的模型。請選擇允許使用的模型，或升級方案。
CHAT_CREDITS_EXHAUSTED—已保留；目前未由任何正式環境的 v2 路由觸發。未定義狀態碼或觸發條件。
CHAT_AGENT_CREDITS_EXHAUSTED—已保留；目前未由任何正式環境的 v2 路由觸發。未定義狀態碼或觸發條件。
CHAT_CONVERSATION_MISMATCH404聊天請求提供了格式正確的 conversationId（≤128 字元），但該值無法對應到此代理程式的任何 API v2 對話。超過 128 字元的 conversationId 會提早以 400 VALIDATION_INVALID_BODY 拒絕，而非回傳此代碼。省略 conversationId 會開始一個新對話。
CHAT_RETRY_MESSAGE_NOT_FOUND404重試操作收到非正整數的訊息 ID，或目標訊息不是該 API v2 對話中的 AI 助理訊息。工具紀錄不能作為重試目標。
CHAT_RETRY_NO_USER_MESSAGE400重試目標沒有更早的使用者訊息可供重播。重試會從所選助理回覆前一則的使用者發言重新生成。
INSTAGRAM_NOT_CONNECTED404Instagram 頻道請求所指定的代理程式未連結 Instagram。GET /channels/instagram 會回傳 { "connected": false }，而非此代碼。
INSTAGRAM_RECONNECT_REQUIRED409在沒有留言權限的情況下啟用留言轉私訊功能，或在連線狀態並非 connected 時發布對話開場白。請在控制台的「發布 → Instagram」中重新連結帳戶。
INSTAGRAM_AUTOMATION_TARGET_TAKEN409啟用 comment_to_dm 或 story_leads 自動化時，已有另一個啟用中的執行個體以相同貼文或限時動態為目標。請停用另一個執行個體，或改為指定其他貼文或限時動態。草稿一律不會遭到拒絕。
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409啟用 comment_to_dm 或 story_leads 全部適用的自動化（postScope / storyScope "any"）時，已存在同類型且啟用中的全部適用自動化。請先停用現有的全部適用自動化，或改為指定特定貼文或限時動態。
INSTAGRAM_SYNC_IN_PROGRESS409常駐選單或對話開場白的 PATCH 與同一代理程式、同一資源的同步作業重疊。請在目前的發布或清除作業完成後重試。
INSTAGRAM_SYNC_FAILED502常駐選單或對話開場白同步失敗。details.code 是允許清單中的失敗代碼；details.http_status 與 details.meta_code 為數字或 null。絕不會回傳 Meta 的訊息文字，且已儲存的即時快照仍會描述最後確認的狀態。
RATE_LIMIT_TOO_MANY_REQUESTS—已保留；目前未由任何正式環境的 v2 路由觸發。未定義重試時機或 Retry-After 行為。
INTERNAL_SERVER_ERROR500URL 工作建立因非配額原因而失敗，或非串流重試未能產生任何已持久化的助理訊息。回報問題時請附上 x-request-id。

參考文件