Límites de solicitudes

Límites de solicitudes por plan para Listings y Social, la estructura de la respuesta 429 y cómo aplicar esperas progresivas y reintentar.

Listings API contabiliza las solicitudes por cuenta según el límite de solicitudes de tu plan. Mantenerte dentro del límite permite que tu integración responda con agilidad; superarlo devuelve 429 Too Many Requests con todo lo que necesitas para reintentar de forma controlada.

Límites por plan

¿Estás probando la API sin un plan de pago? El pase de un día gratuito para el entorno de pruebas devuelve sus límites de solicitudes vigentes junto con la clave de API cuando activas el pase.

Los límites dependen del plan y se aplican por cuenta: todas las claves de API de una cuenta consumen la misma cuota. Las solicitudes se contabilizan en tres intervalos: un límite de ráfaga por minuto, un límite por hora y un límite diario. Todas las solicitudes tienen el mismo coste, independientemente del endpoint. La prueba gratuita utiliza el plan que elegiste, por lo que tiene los límites de ese plan desde la primera solicitud.

Social consume la misma cuota

Los endpoints de Social consumen la misma cuota de solicitudes por cuenta que todos los demás. Un POST /social/bulk-posts que contiene 500 filas consume una solicitud, no 500, por lo que las operaciones masivas son la forma más económica de cargar mucho contenido.

Listings y Social son suscripciones independientes, pero no tienen cuotas independientes. Una cuenta con ambas obtiene los límites más altos de los dos niveles, aplicados una sola vez a todos los endpoints: no se suman ni se asigna una cuota por producto. A un cliente con Listings Launch y Social Growth se le aplican las cifras de Growth indicadas arriba para todo su tráfico.

La respuesta 429

Cuando superas un límite, la API devuelve HTTP 429 y la respuesta de error estándar. Hay tres campos relevantes para los reintentos:

• retry_after_seconds: cuánto tiempo debes esperar antes de reintentar. La cabecera HTTP Retry-After contiene el mismo valor cuando está presente.
• correlation_id: un identificador de solicitud que debes proporcionar si te pones en contacto con el equipo de soporte.
• doc_url: un enlace a la entrada rate_limited de la referencia de códigos de error.

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Gestión de respuestas 429 con esperas progresivas

Respeta retry_after_seconds cuando esté presente y, en caso contrario, aplica una espera exponencial: duplica el tiempo de espera con cada 429 consecutivo hasta un límite máximo, con una pequeña variación aleatoria para que un conjunto de clientes no reintente al mismo tiempo.

import randomimport time import requests MAX_RETRIES = 5  def get_with_backoff(url: str, headers: dict, max_retries: int = MAX_RETRIES):    for attempt in range(max_retries):        resp = requests.get(url, headers=headers)        if resp.status_code != 429:            resp.raise_for_status()            return resp.json()         # Prefer the server's hint; fall back to exponential backoff + jitter.        body = resp.json().get("error", {})        retry_after = body.get("retry_after_seconds")        if retry_after is None:            retry_after = min(2 ** attempt, 30) + random.uniform(0, 1)        time.sleep(retry_after)     raise RuntimeError("Still rate limited after retrying")

Mantenerte por debajo del límite

• Solicita una página a la vez: los bucles de paginación en paralelo sin pausas son la causa más común de respuestas 429. Lee pageInfo.hasNextPage y solicita la siguiente página solo cuando hayas recibido la actual.
• Filtra en el servidor con el parámetro de consulta filter en lugar de obtener todas las páginas y descartar filas en el cliente.
• Almacena en caché las respuestas que no cambian con frecuencia en lugar de volver a obtenerlas en cada solicitud.