# 錯誤與速率限制

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

錯誤以 JSON 回傳，包含固定的 `error` 代碼和給人看的 `message`：

```json
{ "error": "auth_required", "message": "This tool needs a TerraLab account. Connect TerraLab in your assistant's settings; see https://terra-lab.ai/mcp." }
```

請依 `error` 判斷，不要依 `message`：訊息的措辭可能會改變。

## HTTP 錯誤

| 狀態 | `error` | 意思 | 該怎麼做 |
| --- | --- | --- | --- |
| 400 | `invalid_input` | 請求本文不是工具引數的 JSON 物件。 | 修正請求本文。 |
| 400 | `bad_request` | 無法讀取該請求。 | 檢查 JSON 與標頭。 |
| 401 | `auth_required` | 沒有送出金鑰或 token。 | 送出 `Authorization: Bearer <key>`。 |
| 401 | `invalid_token` | 金鑰或 token 無效、已撤銷或已過期。 | 建立新金鑰，或讓代理程式重新登入。 |
| 401 | `access_revoked` | 該應用程式已從儀表板中斷連線。 | 重新連接代理程式。 |
| 402 | `balance_required` | 本月免費呼叫已用完，或該操作需付費，而餘額為零。 | 儲值；回應附有 `hint` 和 `account_url`。 |
| 404 | `not_found` | 沒有這個 API 路徑。 | 檢查網址。 |
| 404 | `unknown_tool` | 沒有這個名稱的工具。 | 用 `GET /v1/tools` 列出工具。 |
| 405 | `method_not_allowed` | 工具要用 `POST` 呼叫。 | 改用 `POST`。 |
| 413 | `too_large` | 請求本文太大。 | 送出較小的檔案或較少的要素。 |
| 429 | `rate_limited` | 過去一分鐘內的請求太多。 | 等待 `Retry-After` 指定的秒數後重試。 |
| 429 | `daily_limit` | 帳號已達每日安全上限。 | 隔天（UTC）再試，或寫信給支援團隊。 |
| 503 | `unavailable` | 帳號服務沒有回應。 | 等待 `Retry-After` 指定的秒數後重試。 |

## 工具錯誤

工具有執行但無法回答時，會回傳 `200` 並帶有 `isError: true`。此時 `structuredContent` 會包含 `code`、`message`，多數情況下還有一個 `hint`，說明該調整什麼：找不到某個地點、區域太大、涵蓋不到某個國家。

```json
{
  "structuredContent": { "code": "...", "message": "...", "hint": "..." },
  "content": [{ "type": "text", "text": "..." }],
  "isError": true
}
```

## 哪些會計入用量

失敗或查無結果的呼叫不會計入：已扣的免費呼叫或餘額會退還。只有帶有結果的回答才算數。

## 速率限制

每個帳號每分鐘可發出 60 次呼叫。超過後，API 會回應 `429` 與 `Retry-After: 60`。請把批次工作分散在較長的時間內，並以遞增的延遲重試：

```python
import time
import requests

def call(url, headers, body, attempts=5):
    for attempt in range(attempts):
        response = requests.post(url, headers=headers, json=body, timeout=120)
        if response.status_code not in (429, 503):
            return response
        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
    return response
```

只重試 `429` 和 `503`。`401` 或 `402` 再試一次也不會通過。

Source: https://terra-lab.ai/zh-TW/docs/errors · Updated 2026-10-27