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

4 min czytaniaZaktualizowano 23 paź 2026Markdown

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:

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

Nagłówek to dokładnie Authorization: Bearer <token>, z wyrazem Bearer i jedną spacją.
Token został skopiowany w całości. Pokazywany jest tylko raz, przy tworzeniu.
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.
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.

Znajdź uprawnienie w kolumnie Permission endpointu.
W Users › API & MCP kliknij Edit przy tokenie i zaznacz je.
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.

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 sam ponawia 429 i 5xx.

Nieudane webhooki #

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

Odpowiadaj szybko. Zwróć 2xx od razu, potem wykonuj wolną pracę w tle.
Sprawdź podpis na surowym ciele, przed parsowaniem JSON. Ciało sparsowane i ponownie zserializowane nigdy się nie zgadza.
Sprawdź zegar serwera. Znacznik czasu starszy niż 5 minut jest odrzucany przez przykładowy kod, więc zegar z dryftem odrzuca każdą dostawę.
Akceptuj oba wartości v1 podczas rotacji sekretu.
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.

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.

Czy to było pomocne?