Hilfe

Fehler und Rate Limits

Fehler kommen als JSON mit einem stabilen error-Code und einer message, die für Menschen geschrieben ist:

{ "error": "auth_required", "message": "This tool needs a TerraLab account. Connect TerraLab in your assistant's settings; see https://terra-lab.ai/mcp." }

Verzweigen Sie nach error, nie nach message: Der Wortlaut kann sich ändern.

HTTP-Fehler

Status	`error`	Bedeutung	Was zu tun ist
400	`invalid_input`	Der Body ist kein JSON-Objekt mit den Tool-Argumenten.	Korrigieren Sie den Request-Body.
400	`bad_request`	Die Anfrage konnte nicht gelesen werden.	Prüfen Sie das JSON und die Header.
401	`auth_required`	Es wurde kein Key und kein Token gesendet.	Senden Sie `Authorization: Bearer <key>`.
401	`invalid_token`	Der Key oder das Token ist ungültig, widerrufen oder abgelaufen.	Erstellen Sie einen neuen Key oder lassen Sie den Agenten sich erneut anmelden.
401	`access_revoked`	Die App wurde im Dashboard getrennt.	Verbinden Sie den Agenten erneut.
402	`balance_required`	Die kostenlosen Aufrufe des Monats sind aufgebraucht oder die Operation ist kostenpflichtig, und das Guthaben ist leer.	Laden Sie Guthaben auf; die Antwort enthält `hint` und `account_url`.
404	`not_found`	Es gibt diesen API-Pfad nicht.	Prüfen Sie die URL.
404	`unknown_tool`	Kein Tool hat diesen Namen.	Listen Sie die Tools mit `GET /v1/tools`.
405	`method_not_allowed`	Tools werden mit `POST` aufgerufen.	Verwenden Sie `POST`.
413	`too_large`	Der Request-Body ist zu groß.	Senden Sie eine kleinere Datei oder weniger Features.
429	`rate_limited`	Zu viele Anfragen in der letzten Minute.	Warten Sie `Retry-After` Sekunden und versuchen Sie es dann erneut.
429	`daily_limit`	Das Konto hat seine tägliche Sicherheitsgrenze erreicht.	Versuchen Sie es am nächsten Tag (UTC) erneut oder schreiben Sie an den Support.
503	`unavailable`	Der Kontodienst hat nicht geantwortet.	Versuchen Sie es nach `Retry-After` Sekunden erneut.

Tool-Fehler

Ein Tool, das läuft, aber nicht antworten kann, liefert 200 mit isError: true. Sein structuredContent enthält dann code, message und meistens einen hint, der sagt, was zu ändern ist: ein Ort, der nicht gefunden wurde, ein zu großes Gebiet, ein Land, das es nicht abdeckt.

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

Was gezählt wird

Ein Aufruf, der fehlschlägt oder nichts findet, wird nicht gezählt: Der kostenlose Aufruf oder der vom Guthaben abgebuchte Betrag wird zurückgegeben. Nur Antworten mit einem Ergebnis zählen.

Rate Limits

Jedes Konto kann 60 Aufrufe pro Minute machen. Darüber antwortet die API mit 429 und Retry-After: 60. Verteilen Sie Batch-Jobs über die Zeit und versuchen Sie es mit wachsender Wartezeit erneut:

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

Wiederholen Sie nur 429 und 503. Ein 401 oder 402 geht beim zweiten Versuch nicht durch.

Aktualisiert am 2026-10-27