說明

錯誤與速率限制

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

{ "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，說明該調整什麼：找不到某個地點、區域太大、涵蓋不到某個國家。

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

哪些會計入用量

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

速率限制

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

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 再試一次也不會通過。

更新於 2026-10-27