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:
- Limit na sekundę — wysyłasz więcej zapytań niż wynosi
rate_limitklucza 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.
- 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.
- 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_metersi 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,addresslubparcel_id. - Typ pola niezgodny (np.
radius_metersjako string zamiast liczby). latitude/longitudepoza 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).