# エラーとレート制限

> 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 パスはありません。 | URL を確認してください。 |
| 404 | `unknown_tool` | その名前のツールはありません。 | `GET /v1/tools` でツールの一覧を確認してください。 |
| 405 | `method_not_allowed` | ツールは `POST` で呼び出します。 | `POST` を使ってください。 |
| 413 | `too_large` | リクエストボディが大きすぎます。 | ファイルを小さくするか、フィーチャーの数を減らして送ってください。 |
| 429 | `rate_limited` | 直近 1 分間のリクエストが多すぎます。 | `Retry-After` の秒数だけ待ってから、再試行してください。 |
| 429 | `daily_limit` | アカウントが、1 日の安全上限に達しました。 | 翌日（UTC）に再試行するか、サポートにご連絡ください。 |
| 503 | `unavailable` | アカウントサービスが応答しませんでした。 | `Retry-After` の秒数が過ぎてから再試行してください。 |

## ツールのエラー

ツールは実行されたものの回答できなかった場合、`200` と `isError: true` を返します。このとき `structuredContent` に `code`、`message`、そして多くの場合、何を変更すべきかを示す `hint` が入ります。たとえば、場所が見つからない、エリアが大きすぎる、対応していない国である、といった内容です。

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

## 課金の対象

失敗した呼び出しや、結果が見つからなかった呼び出しは数えられません。無料の呼び出し、または残高から差し引かれた金額は戻ります。結果のある回答だけが課金の対象です。

## レート制限

すべてのアカウントは、1 分あたり 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/ja/docs/errors · Updated 2026-10-27