Błędy w skrócie
| Otrzymujesz | Znaczy to | Co zrobić |
|---|---|---|
| 429 Too Many Requests | Wszystkie sloty Twojego adresu IP były zajęte przez 15 sekund. | Poczekaj przed kolejnym zapytaniem, wysyłaj po jednym zapytaniu naraz, sprawdź swoje sloty pod /api/status. |
| 504 Gateway Timeout | Serwer nie znalazł w ciągu 15 sekund miejsca na czas i pamięć, które deklaruje Twoje zapytanie. | Poproś o mniej: mniejszy [timeout] lub [maxsize], mniejszy obszar. Albo spróbuj później. |
200 z uwagą runtime error o czasie | Zapytanie trwało dłużej niż jego [timeout] (180 sekund, jeśli go nie ustawisz) i zostało zatrzymane. | Zawęź obszar lub filtry albo podnieś timeout; wyższy timeout trudniej dopuścić do wykonania. |
200 z uwagą runtime error o pamięci | Zapytanie potrzebowało więcej niż jego [maxsize] (512 MiB, jeśli go nie ustawisz). | Zawęź zapytanie, wypisuj mniej (out center zamiast out geom) albo podnieś [maxsize]. |
Błędy ze statusem 200 łatwo przeoczyć: odpowiedź jest poprawnym JSON-em bez elementów, a przyczyna jest tylko w polu remark. Sprawdzaj je w kliencie.
Jak działa limit żądań
Overpass zlicza żądania na użytkownika, a użytkownikiem jest Twój adres IP (dla IPv6 jego pierwsze 64 bity), chyba że wyślesz klucz użytkownika. Każdy użytkownik ma kilka slotów. Zapytanie zajmuje slot na czas działania i na okres odpoczynku po nim. Okres odpoczynku to ułamek czasu działania, gdy serwer jest spokojny, i wielokrotność czasu działania, gdy jest zajęty, więc w intensywnym dniu ten sam klient przepuści mniej zapytań.
Zapytanie, które nie znajdzie wolnego slotu, czeka do 15 sekund, a potem dostaje 429. Dwa publiczne serwery za overpass-api.de liczą sloty osobno.
Żeby zobaczyć własny stan, otwórz stronę statusu:
curl https://overpass-api.de/api/statusJej trzecia linia, po „Rate limit:”, to liczba Twoich slotów. Linie od szóstej mówią, kiedy zajęte sloty się zwolnią.
Dlaczego małe zapytanie może dostać 504
Przed uruchomieniem zapytania serwer sprawdza deklarowany czas i pamięć: [timeout] domyślnie wynosi 180 sekund, a [maxsize] 512 MiB. Zapytanie jest przyjmowane tylko wtedy, gdy obie wartości mieszczą się w połowie tego, co serwer ma w tej chwili wolne. Jeśli się nie mieszczą, czeka do 15 sekund i dostaje 504. Zapytanie z deklaracją [timeout:900] „na wszelki wypadek” może więc zostać odrzucone na zajętym serwerze, a to samo zapytanie z [timeout:60] się wykona.
Poprawki po stronie klienta
- Wysyłaj po jednym zapytaniu naraz. Główny serwer nie dopuszcza równoległych skryptów.
- Po 429 lub innym statusie błędu zrób przerwę przed kolejnym zapytaniem; wiki OpenStreetMap sugeruje 30 sekund.
- Buforuj odpowiedzi. Dane map w większości aplikacji nie zmieniają się z minuty na minutę.
- Wysyłaj nagłówek
User-Agentz nazwą swojej aplikacji, jak wymaga polityka użycia. - Deklaruj
[timeout]zbliżony do potrzeb zapytania, a nie największą możliwą wartość. - Dziel duży obszar na mniejsze prostokąty i używaj
out centerlubout tags, gdy nie potrzebujesz pełnej geometrii.
Na co pozwala serwer publiczny
Polityka użycia na wiki OpenStreetMap uznaje mniej niż około 10 000 zapytań i 1 GB pobranych danych dziennie za niezakłócające pracy innych użytkowników i prosi, by regularne użycie mieściło się sto razy poniżej tej granicy. Aplikacja liczy wszystkich swoich użytkowników łącznie. Użycie komercyjne ma przenieść się na serwery płatne lub własne, a wiki obecnie pisze, że główny serwer jest przeciążony i nie należy oczekiwać, że będzie niezawodny.
Jeśli Twój backend wysyła zapytania Overpass w imieniu użytkowników, wszyscy dzielą sloty Twojego serwera. To zwykle moment, by poszukać innej opcji.
Opcje, gdy serwer publiczny nie wystarcza
- Własny Overpass. Pełny język zapytań i aktualizacje co minutę, ale sam dbasz o serwer, jego dysk i aktualizacje.
- Płatna instancja Overpass. Wiki wymienia kilka, z cenami i limitami.
- Nasz endpoint. Własny klucz i limity, od 500 żądań dziennie za darmo. Odpowiada na podzbiór Overpass QL z bazy odświeżanej co miesiąc, bez rekursji; strona o alternatywie dla Overpass API dokładnie wymienia, co jest obsługiwane, a przykłady pokazują typowe zapytania.
Źródła: dokumentacja Overpass API, „Commons” oraz strona Overpass API na wiki OpenStreetMap, odczytane 7 listopada 2026.