Hulp

Fouten en rate limits

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

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

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

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.

Bijgewerkt op 2026-10-27