# Fehler und Rate Limits

> 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.

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

```json
{ "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.

```json
{
  "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:

```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
```

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

Source: https://terra-lab.ai/de/docs/errors · Updated 2026-10-27