> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 錯誤與限制

> Agent API 的狀態碼、錯誤格式、逾時與併發建議

## 錯誤格式

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

```json theme={null}
{ "error": { "type": "not_found_error", "message": "Agent not found in this workspace" } }
```

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

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

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

***

## 狀態碼

| 狀態    | `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 或排程                        |

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

***

## 限制與時間

|            |                            |
| ---------- | -------------------------- |
| **單一回合上限** | 10 分鐘的 Agent 執行時間          |
| **一般短回合**  | 約 10–20 秒，主要花在沙箱與 Agent 啟動 |
| **附件**     | 每回合 10 個檔案、解碼後共 10 MiB     |
| **請求內容**   | 15 MiB                     |
| **速率限制**   | 此端點沒有 — 請自行控制併發            |

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

### 用戶端設定

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

### 併發

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

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

***

## 可觀測性

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