# Rozwiązywanie problemów z API: typowe błędy

_API · 4 min czytania · Zaktualizowano 2026-10-23 · https://lanachat.ai/guides/pl/api-troubleshooting/_

Każdy endpoint w referencji jest dziś oznaczony jako **Planned**: to opublikowany kontrakt, który jeszcze nie odpowiada. Ta strona wymienia błędy, które API będzie zwracać, aby Twój kod mógł je obsługiwać od pierwszego dnia.

## Najpierw przeczytaj błąd

Każdy błąd zwraca status 4xx lub 5xx z takim samym ciałem:

```json
{ "error": { "code": "forbidden", "message": "…" } }
```

`message` to zwykłe zdanie po angielsku, które mówi, co poszło nie tak. Zaloguj je, ale rozgałęziając kod, korzystaj z `code`, nigdy z `message`.

## 401 unauthorized

API nie zaakceptowało Twojego tokena. Sprawdź, w tej kolejności:

1. Nagłówek to dokładnie `Authorization: Bearer <token>`, z wyrazem `Bearer` i jedną spacją.
2. Token został skopiowany w całości. Pokazywany jest tylko raz, przy tworzeniu.
3. Token jest nadal aktywny. W **Users › API & MCP** tabela **Access tokens** pokazuje datę wygaśnięcia i status każdego tokena, a **Show revoked tokens** wyświetla stare.
4. Jeśli wygasł lub został unieważniony, utwórz nowy (lub **Rotate** go) i zaktualizuj zmienną środowiskową.

## 403 forbidden

Token jest ważny, ale nie ma uprawnienia wymaganego przez endpoint. Każdy endpoint w referencji podaje swoje uprawnienie, np. `can_fan_read` lub `can_sales_read`.

1. Znajdź uprawnienie w kolumnie **Permission** endpointu.
2. W **Users › API & MCP** kliknij **Edit** przy tokenie i zaznacz je.
3. Wywołaj `GET /v1/workspace`: odpowiedź pokaże, co token może robić.

`403` pojawia się też, gdy token niebędący tokenem właściciela wysyła nagłówek `LanaChat-Workspace`. Usuń go.

## 429 rate_limited

Każdy token może wysłać 600 zapytań na minutę. Każda odpowiedź zawiera `RateLimit-Remaining` i `RateLimit-Reset`.

- Poczekaj liczbę sekund podaną w `Retry-After`, potem spróbuj ponownie.
- Przeglądaj listy z `limit=100` zamiast wywoływać osobno dla każdego elementu.
- Wysyłanie wiadomości do fans jest też ograniczone przez limity Telegrama: zobacz [Telegram accounts and pools](https://lanachat.ai/guides/pl/api-telegram-accounts/).

## Pozostałe kody

| Status | `code` | Co zrobić |
|---|---|---|
| 400 | `invalid_request` | Brakuje pola lub ma zły format: `message` mówi które |
| 402 | `insufficient_balance` | Doładuj konto przed zakupem |
| 404 | `not_found` | Id nie istnieje w tym workspace: sprawdź, czy używasz właściwego tokena |
| 409 | `conflict` | Zmiana łamie regułę lub `Idempotency-Key` został użyty ponownie z innym ciałem |
| 500 | `server_error` | Spróbuj ponownie później z tym samym `Idempotency-Key` |

Wysyłaj `Idempotency-Key` przy każdym `POST`: ponowne wywołanie nie wykona pracy dwa razy. Pomocnik w [the quick start](https://lanachat.ai/guides/pl/api-overview/) sam ponawia `429` i `5xx`.

## Nieudane webhooki

Dostawa jest uznawana za nieudaną, gdy Twój serwer nie odpowie `2xx` w ciągu 10 sekund.

1. **Odpowiadaj szybko.** Zwróć `2xx` od razu, potem wykonuj wolną pracę w tle.
2. **Sprawdź podpis na surowym ciele**, przed parsowaniem JSON. Ciało sparsowane i ponownie zserializowane nigdy się nie zgadza.
3. **Sprawdź zegar serwera.** Znacznik czasu starszy niż 5 minut jest odrzucany przez przykładowy kod, więc zegar z dryftem odrzuca każdą dostawę.
4. **Akceptuj oba wartości `v1`** podczas rotacji sekretu.
5. **Testuj** za pomocą `POST /webhooks/{id}/test` (Planned), które wysyła `ping`, i ponownie wyślij dostawę przez `/deliveries/{delivery_id}/retry` (Planned) po naprawieniu swojej strony.

Nieudane dostawy są ponawiane 8 razy przez około 24 godziny. Po 3 dniach niepowodzeń endpoint jest wstrzymany; wznowisz go przez `PATCH /webhooks/{id}` (Planned). To samo zdarzenie może przyjść dwa razy: ignoruj duplikaty po `id`. Zobacz [Webhooks](https://lanachat.ai/guides/pl/api-webhooks/).

## Nadal masz problem?

Otwórz dymek pomocy w prawym dolnym rogu Console i napisz do zespołu z endpointem, statusem, `code` i czasem wywołania. Nigdy nie wklejaj samego tokena. Zobacz [Get help](https://lanachat.ai/guides/pl/get-help/).

## Powiązane artykuły

- [LanaChat API: szybki start, uwierzytelnianie i błędy](https://lanachat.ai/guides/pl/api-overview/)
- [API: webhooki, zdarzenia i podpisy](https://lanachat.ai/guides/pl/api-webhooks/)
- [API: członkowie zespołu, role i tokeny dostępu](https://lanachat.ai/guides/pl/api-team/)
- [Szybkie przepisy API: kopiuj, wklej, uruchom](https://lanachat.ai/guides/pl/api-recipes/)