コンテンツへスキップ
TerraLabTerraLabドキュメント

ヘルプ

Markdown

エラーとレート制限

エラーは 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意味対処方法
400invalid_inputボディが、ツールの引数を持つ JSON オブジェクトではありません。リクエストボディを修正してください。
400bad_requestリクエストを読み取れませんでした。JSON とヘッダーを確認してください。
401auth_requiredキーも token も送られていません。Authorization: Bearer <key> を送ってください。
401invalid_tokenキーまたは token が無効、無効化済み、または期限切れです。新しいキーを作成するか、エージェントに再度サインインさせてください。
401access_revokedダッシュボードからアプリの接続が解除されました。エージェントを再接続してください。
402balance_required今月の無料の呼び出しを使い切ったか、有料の操作で、残高が空です。残高を追加してください。回答には hint と account_url が含まれます。
404not_foundそのような API パスはありません。URL を確認してください。
404unknown_toolその名前のツールはありません。GET /v1/tools でツールの一覧を確認してください。
405method_not_allowedツールは POST で呼び出します。POST を使ってください。
413too_largeリクエストボディが大きすぎます。ファイルを小さくするか、フィーチャーの数を減らして送ってください。
429rate_limited直近 1 分間のリクエストが多すぎます。Retry-After の秒数だけ待ってから、再試行してください。
429daily_limitアカウントが、1 日の安全上限に達しました。翌日（UTC）に再試行するか、サポートにご連絡ください。
503unavailableアカウントサービスが応答しませんでした。Retry-After の秒数が過ぎてから再試行してください。

ツールのエラー

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

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

課金の対象

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

レート制限

すべてのアカウントは、1 分あたり 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 更新