# 错误与速率限制

> 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-CN/docs/errors · Updated 2026-10-27