帮助

错误与速率限制

错误以 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