錯誤與限制

錯誤格式

串流開始之前發生的錯誤是 JSON，格式與 Anthropic 相同：

{ "error": { "type": "not_found_error", "message": "Agent not found in this workspace" } }

串流開始之後的錯誤，會以 SSE 事件出現在一個已經回傳 200 的回應中：

event: error
data: {"type":"error","error":{"type":"api_error","message":"…"}}

200 只代表這一回合已經開始。請務必處理 error 事件，並把「沒有以 message_stop 結束的串流」視為失敗的回合。

狀態	`error.type`	原因	處理方式
`400`	`invalid_request_error`	缺少內容、`messages` 為空，或其中沒有 user 角色的文字	送出非空的 `messages`，且至少包含一則 `role: "user"`
`401`	`authentication_error`	金鑰遺失、無法辨識或格式錯誤	檢查 `X-Api-Key` header
`401`	—	`{"message": "API key has been revoked"}`	建立新的金鑰
`401`	憑證錯誤	該 Agent 沒有可用的 LLM 憑證	在 workspace 中補上 Agent 的模型憑證
`403`	`permission_error`	Viewer 角色，或寫入他人分享的對話	改用 Operator 以上的金鑰；或分支該對話
`404`	`not_found_error`	`Agent not found in this workspace`	確認 Agent 名稱以及金鑰是否屬於該 Agent 的 workspace
`404`	`not_found_error`	`Conversation not found`	該 id 屬於其他 Agent、workspace 或使用者
`404`	HTML 頁面	HTTP 方法錯誤（例如對 `/v1/messages` 發 `GET`）	路由綁定特定方法，請使用文件標示的方法
`409`	`conflict_error`	分支目標 id 已存在	分支時省略 `conversation_id`，或換一個
`413`	—	請求內容超過 15 MiB	縮小附件（解碼後上限 10 MiB）
`501`	`not_implemented`	`metadata.delivery: "async"`	背景執行請改用 webhook 或排程

為什麼 workspace 不符是 404 而不是 403

Agent 的查詢會限縮在呼叫金鑰所屬的 workspace 內，而且無論是「Agent 不存在」或「存在但你看不到」，回報方式都相同 — 這樣就沒有人能藉此探測其他 workspace 的 Agent 名稱。如果你確定名稱正確，問題幾乎都出在金鑰上。

長時間執行但仍在輸出或使用工具的回合會繼續進行；執行環境只會中止真正失去網路連線、或超過上限的回合。被這樣中止的回合仍保有接續指標，因此在同一段對話送出「繼續」即可從中斷處接續。

逾時要設寬鬆。 預設的 HTTP 用戶端逾時（30 秒）會切斷正常的 Agent 工作。請至少給 10 分鐘，並以串流方式逐步讀取。
關閉會緩衝的代理。 任何會緩衝回應的中介層都會破壞串流。此端點會送出 Cache-Control: no-cache, no-transform。
重試要以對話為單位，而不是以請求為單位。 由於接續的回合會附加到持久的歷史紀錄，盲目重試一個部分成功的回合可能造成重複工作。較好的做法是在同一個 conversation_id 上送出新的指示。
連續回合之間要等待接續指標。 在串流剛結束就送出下一則訊息，可能在工作階段尚未記錄前就接續對話，導致 Agent 靜默地失去上一回合的脈絡。詳見接續對話。

每一段對話在單一沙箱中執行。對同一個 conversation_id 同時送出兩個回合，會共用該沙箱並在對話紀錄上互相競爭。

同一段對話內請依序送出；要平行處理請跨對話。用 conversation_id 當 key 的佇列，是最簡單且正確的用戶端設計。

每一個回合都會在該 Agent 上留下一筆執行紀錄 — 狀態、耗時與結果 — 並且會區分 API key 流量與網頁介面流量，因此你可以在 Agent 的活動頁面上篩選出自己整合的執行。失敗的回合會保留錯誤訊息，通常比從串流回推更快找到原因。