# Fouten en 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.

Fouten komen als JSON met een vaste `error`-code en een `message` die voor een mens is geschreven:

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

Vertak op `error`, nooit op `message`: de tekst kan veranderen.

## HTTP-fouten

| Status | `error` | Betekenis | Wat te doen |
| --- | --- | --- | --- |
| 400 | `invalid_input` | De body is geen JSON-object met de toolargumenten. | Corrigeer de body van de aanvraag. |
| 400 | `bad_request` | De aanvraag kon niet worden gelezen. | Controleer de JSON en de headers. |
| 401 | `auth_required` | Er is geen sleutel of token meegestuurd. | Stuur `Authorization: Bearer <key>` mee. |
| 401 | `invalid_token` | De sleutel of het token is ongeldig, ingetrokken of verlopen. | Maak een nieuwe sleutel, of laat de agent opnieuw inloggen. |
| 401 | `access_revoked` | De app is losgekoppeld vanuit het dashboard. | Verbind de agent opnieuw. |
| 402 | `balance_required` | De gratis aanroepen van de maand zijn op, of de bewerking is betaald, en het saldo is leeg. | Waardeer op; het antwoord bevat `hint` en `account_url`. |
| 404 | `not_found` | Dit API-pad bestaat niet. | Controleer de URL. |
| 404 | `unknown_tool` | Er is geen tool met die naam. | Toon de tools met `GET /v1/tools`. |
| 405 | `method_not_allowed` | Tools worden aangeroepen met `POST`. | Gebruik `POST`. |
| 413 | `too_large` | De body van de aanvraag is te groot. | Stuur een kleiner bestand of minder features. |
| 429 | `rate_limited` | Te veel aanvragen in de laatste minuut. | Wacht het aantal seconden in `Retry-After` en probeer opnieuw. |
| 429 | `daily_limit` | Het account heeft zijn dagelijkse veiligheidsplafond bereikt. | Probeer de volgende dag (UTC) opnieuw of schrijf naar support. |
| 503 | `unavailable` | De accountservice antwoordde niet. | Probeer opnieuw na `Retry-After` seconden. |

## Toolfouten

Een tool die draait maar niet kan antwoorden, geeft `200` terug met `isError: true`. Zijn `structuredContent` bevat dan `code`, `message` en meestal een `hint` die zegt wat je moet aanpassen: een plaats die hij niet kon vinden, een te groot gebied, een land dat hij niet dekt.

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

## Wat wordt geteld

Een aanroep die mislukt of niets vindt, wordt niet geteld: de gratis aanroep of het bedrag dat van het saldo is afgeschreven, krijg je terug. Alleen antwoorden met een resultaat tellen mee.

## Rate limits

Elk account kan 60 aanroepen per minuut doen. Daarboven antwoordt de API met `429` en `Retry-After: 60`. Spreid batchtaken over de tijd en probeer opnieuw met een oplopende wachttijd:

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

Probeer alleen `429` en `503` opnieuw. Een `401` of `402` lukt niet bij een tweede poging.

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