Skip to Content
FAQ i rozwiązywanie problemów

FAQ i rozwiązywanie problemów

Praktyczne scenariusze i rozwiązania najczęstszych problemów z API LokalScore. Kompletna tabela kodów błędów znajduje się w Autentykacja → Obsługa błędów.

429 — Przekroczono limit zapytań

Objaw: odpowiedź 429 Too Many Requests z komunikatem:

{ "detail": "Przekroczono limit zapytań (Dopuszczalny limit: 10 req/sec)" }

albo

{ "detail": "Przekroczono miesięczny limit zapytań API (Maksymalnie: 50000/miesięcznie)" }

Przyczyny i rozwiązania:

  1. Limit na sekundę — wysyłasz więcej zapytań niż wynosi rate_limit klucza w ciągu 1 sekundy. Sprawdź aktualny limit w Plany i limity.
    • Wdróż retry z wykładniczym backoffem i jitterem.
    • Rozważ podniesienie planu z wyższym req/s.
  2. Limit miesięczny wyczerpany, bez overage — plan nie ma zdefiniowanej ceny za dodatkowe zapytanie, więc nadwyżka jest blokowana.
    • Przejdź na wyższy plan lub plan z overage, aby zapytania ponad limit były rozliczane indywidualnie (zamiast blokady).
    • Monitoruj zużycie w Portalu klienta w sekcji Metryki zużycia.
  3. Per-IP limit nginx — limit 30 req/s (burst 10) dla całego /api/. Jeśli masz wiele procesów za jednym IP, rozważ buforowanie lub mniejsze tempo.

504 — Przekroczono czas obliczeń

Objaw: odpowiedź 504 Gateway Timeout.

Przyczyny i rozwiązania:

  • Większy radius_meters (np. 2000+) wydłuża czas analizy sąsiedztwa (H3, POI, transakcje).
  • Zmniejsz radius_meters i spróbuj ponownie.
  • Ustaw dłuższy timeout po stronie klienta — rekomendowane 30 s dla /evaluate.
  • Jeśli problem występuje stale dla małych promieni, skontaktuj się z supportem — może to być przeciążenie backendu.

422 — Błąd walidacji

Objaw: odpowiedź 422 Unprocessable Entity z listą pól z błędami.

Przyczyny i rozwiązania:

  • Brak wymaganego pola — musisz podać jedną z lokalizacji: latitude + longitude, address lub parcel_id.
  • Typ pola niezgodny (np. radius_meters jako string zamiast liczby).
  • latitude/longitude poza zakresem (-90..90 / -180..180).
{ "detail": [ { "loc": ["body", "longitude"], "msg": "Input should be a valid number", "type": "float_parsing" } ] }

Rozwiązanie: zweryfikuj treść żądania względem schematu w dokumentacji API (przycisk Authorize + przykładowe żądanie).

Geokodowanie — „Must provide either (latitude and longitude), or address, or parcel_id”

Objaw: odpowiedź 400 Bad Request:

{ "detail": "Must provide either (latitude and longitude), or address, or parcel_id." }

Przyczyny i rozwiązania:

  • Nie podałeś żadnej z trzech metod lokalizacji. Podaj przynajmniej jedną:
    • latitude + longitude (EPSG:4326),
    • address (np. ul. Legnicka 12, Wrocław),
    • parcel_id (np. 026401_1.0022.AR_11.54/2).
  • Adres nie został rozwiązany przez geokoder — sprawdź pisownię, dodaj miejscowość. Możesz przetestować zapytanie przez /prg/autocomplete, aby zweryfikować poprawny format adresu.

Inne typowe pytania

Jak szybko zaktualizują się limity po zmianie planu?

Zmiana limitu w Portalu odświeża metadane klucza. Backend cache’uje metadane klucza w Redis na 5 minut — zmiany mogą być widoczne z opóźnieniem do 5 minut.

Czy mogę używać jednego klucza dla wielu serwisów?

Tak, ale limity są wspólne dla wszystkich żądań z tym kluczem. Dla izolacji obciążeń wygeneruj osobne klucze w Portalu i przypisz je do odpowiednich planów.

Czy autocomplete wymaga klucza API?

Nie — GET /api/v1/prg/autocomplete i GET /api/v1/teryt/autocomplete są publiczne (bez auth), ale podlegają per-IP limitom nginx. Pozostałe endpointy wymagają klucza Bearer.

Gdzie znajdę aktualne plany i limity?

Wszystkie plany i limity są pobierane na żywo z bazy na stronie Plany i limity (endpoint GET /api/v1/pricing).

LokalScore
System scoringu lokalizacji i wyceny nieruchomości w Polsce.
© 2026 LokalScore. Wszelkie prawa zastrzeżone.