# Błędy i limity zapytań

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

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

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

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

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

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

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