Pomoc

Błędy i limity zapytań

Błędy przychodzą jako JSON ze stałym kodem error i komunikatem message napisanym dla człowieka:

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

Rozgałęziaj logikę po error, nigdy po message: jego treść może się zmienić.

Błędy HTTP

Status	`error`	Znaczenie	Co zrobić
400	`invalid_input`	Treść żądania nie jest obiektem JSON z argumentami narzędzia.	Popraw treść żądania.
400	`bad_request`	Nie udało się odczytać żądania.	Sprawdź JSON i nagłówki.
401	`auth_required`	Nie wysłano klucza ani tokena.	Wyślij `Authorization: Bearer <key>`.
401	`invalid_token`	Klucz lub token jest nieprawidłowy, unieważniony albo wygasł.	Utwórz nowy klucz lub pozwól agentowi zalogować się ponownie.
401	`access_revoked`	Aplikacja została odłączona w panelu.	Podłącz agenta ponownie.
402	`balance_required`	Darmowe wywołania z tego miesiąca się skończyły albo operacja jest płatna, a saldo jest puste.	Doładuj saldo; odpowiedź zawiera `hint` i `account_url`.
404	`not_found`	Nie ma takiej ścieżki API.	Sprawdź adres URL.
404	`unknown_tool`	Żadne narzędzie nie ma takiej nazwy.	Wyświetl narzędzia przez `GET /v1/tools`.
405	`method_not_allowed`	Narzędzia wywołuje się przez `POST`.	Użyj `POST`.
413	`too_large`	Treść żądania jest za duża.	Wyślij mniejszy plik lub mniej obiektów.
429	`rate_limited`	Za dużo żądań w ostatniej minucie.	Odczekaj `Retry-After` sekund, potem ponów.
429	`daily_limit`	Konto osiągnęło dzienny limit bezpieczeństwa.	Spróbuj następnego dnia (UTC) lub napisz do wsparcia.
503	`unavailable`	Usługa kont nie odpowiedziała.	Ponów po `Retry-After` sekundach.

Błędy narzędzi

Narzędzie, które działa, ale nie może odpowiedzieć, zwraca 200 z isError: true. Jego structuredContent zawiera wtedy code, message i najczęściej hint mówiący, co zmienić: miejsce, którego nie znalazło, zbyt duży obszar, kraj, którego nie obsługuje.

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

Co jest liczone

Wywołanie, które kończy się błędem lub niczego nie znajduje, nie jest liczone: darmowe wywołanie lub kwota pobrana z salda wraca do Ciebie. Liczą się tylko odpowiedzi z wynikiem.

Limity zapytań

Każde konto może wykonać 60 wywołań na minutę. Po jego przekroczeniu API odpowiada 429 z Retry-After: 60. Rozłóż zadania wsadowe w czasie i ponawiaj z rosnącym opóźnieniem:

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

Ponawiaj tylko 429 i 503. 401 lub 402 nie ustąpi przy drugiej próbie.

Zaktualizowano 2026-10-27