Los errores de un vistazo
| Recibes | Significa | Qué hacer |
|---|---|---|
| 429 Too Many Requests | Todas las plazas de tu dirección IP estuvieron ocupadas durante 15 segundos. | Espera antes de la siguiente consulta, lanza una consulta cada vez, comprueba tus plazas en /api/status. |
| 504 Gateway Timeout | El servidor no encontró hueco, en 15 segundos, para el tiempo y la memoria que declara tu consulta. | Pide menos: un [timeout] o [maxsize] menor, un área más pequeña. O reintenta más tarde. |
200 con un remark de runtime error sobre el tiempo | La consulta tardó más que su [timeout] (180 segundos si no lo indicas) y se detuvo. | Reduce el área o los filtros, o sube el timeout; un timeout mayor es más difícil de admitir. |
200 con un remark de runtime error sobre la memoria | La consulta necesitó más que su [maxsize] (512 MiB si no lo indicas). | Reduce la consulta, imprime menos (out center en lugar de out geom) o sube [maxsize]. |
Los errores con estado 200 son fáciles de pasar por alto: la respuesta es un JSON válido sin elementos, y el motivo solo está en el campo remark. Compruébalo en tu cliente.
Cómo funciona el límite de peticiones
Overpass cuenta las peticiones por usuario, y el usuario es tu dirección IP (en IPv6, sus primeros 64 bits) a menos que envíes una clave de usuario. Cada usuario tiene unas pocas plazas. Una consulta ocupa una plaza mientras se ejecuta y durante un enfriamiento posterior. El enfriamiento es una fracción del tiempo de ejecución cuando el servidor está tranquilo y varias veces ese tiempo cuando está ocupado, así que el mismo cliente consigue pasar menos consultas en un día de mucha carga.
Una consulta que no encuentra plaza libre espera hasta 15 segundos y luego recibe 429. Los dos servidores públicos que hay detrás de overpass-api.de llevan cuentas separadas.
Para ver tu propio estado, abre la página de estado:
curl https://overpass-api.de/api/statusSu tercera línea, tras "Rate limit:", es el número de plazas que tienes. Las líneas desde la sexta indican cuándo se liberan tus plazas ocupadas.
Por qué una consulta pequeña puede recibir 504
Antes de ejecutar una consulta, el servidor comprueba el tiempo y la memoria que declara: [timeout] es 180 segundos por defecto y [maxsize] 512 MiB. Una consulta solo se admite si ambos caben en la mitad de lo que el servidor tiene libre en ese momento. Si no caben, espera hasta 15 segundos y luego recibe 504. Así, una consulta que declara [timeout:900] por precaución puede ser rechazada en un servidor ocupado, mientras que la misma consulta con [timeout:60] se ejecuta.
Arreglos en tu cliente
- Envía una consulta cada vez. El servidor principal no permite scripts en paralelo.
- Tras un 429 u otro estado de error, haz una pausa antes de la siguiente consulta; la wiki de OpenStreetMap sugiere 30 segundos.
- Guarda las respuestas en caché. Los datos del mapa no cambian de un minuto a otro para la mayoría de las aplicaciones.
- Envía un
User-Agentque nombre tu aplicación, como pide la política de uso. - Declara un
[timeout]cercano a lo que necesita la consulta, no el valor más alto. - Divide un área grande en recuadros más pequeños, y pide
out centeroout tagscuando no necesites la geometría completa.
Qué permite el servidor público
La política de uso de la wiki de OpenStreetMap considera que menos de unas 10 000 consultas y 1 GB de descargas al día no molestan a otros usuarios, y pide que el uso regular se mantenga cien veces por debajo. Una aplicación cuenta a todos sus usuarios juntos. Se pide que el uso comercial pase a servidores de pago o alojados por uno mismo, y la wiki dice actualmente que el servidor principal está sobrecargado y que no debe esperarse que sea fiable.
Si tu backend envía consultas Overpass por cuenta de tus usuarios, todos comparten las plazas de tu servidor. Ese es el momento habitual de buscar otra opción.
Opciones cuando el servidor público no basta
- Ejecuta tu propio Overpass. Lenguaje de consulta completo y actualizaciones cada minuto, pero tú te ocupas del servidor, su disco y sus actualizaciones.
- Una instancia de Overpass de pago. La wiki enumera varias, con sus precios y límites.
- Nuestro endpoint. Tu propia clave y tus propios límites, desde 500 peticiones al día gratis. Responde un subconjunto de Overpass QL desde una base de datos que se actualiza cada mes, sin recursión; la página de alternativa a la API de Overpass lista exactamente qué se admite, y los ejemplos muestran consultas habituales.
Fuentes: documentación de Overpass API, "Commons" y la página de Overpass API en la wiki de OpenStreetMap, consultadas el 7 de noviembre de 2026.