Rate limits

Neuroon aplica rate limiting por endpoint, no por plan de subscripción. La cuota por plan (productos sincronizados, búsquedas mensuales) es un concepto separado del throttling de tasa que documenta esta página. Ver Cuotas de plan vs rate limit más abajo.

Hay dos capas de throttling: una sobre /api/plugin/shops/* (autenticada con Shop API Key) y otra sobre /api/widget/* (autenticada con Widget Token). Los límites son globales por endpoint — no varían según el plan.

Límites por endpoint

Endpoint	Límite	Ventana
POST /api/plugin/shops/{shopId}/products/sync	100 req	1 min
GET /api/plugin/shops/me	60 req	1 min
GET /api/plugin/shops/{shopId}/verification-data	20 req	1 min
POST /api/plugin/shops/{shopId}/verify	5 req	5 min
DELETE /api/plugin/shops/{shopId}/verify	5 req	5 min
/api/widget/search*	200 req	1 min
/api/widget/suggestions*	300 req	1 min
/api/widget/compare*	10 req	1 min
/api/widget/analytics*	500 req	1 min
Resto de endpoints rate-limited	100 req	1 min

`widget-compare` es el más restrictivo

Sólo 10 invocaciones por minuto y por shop. Cachéalo agresivamente en el cliente o agrupa comparaciones; agotar este bucket es el caso más frecuente de 429 en widget.

Headers de respuesta

Header	Cuándo se emite	Significado
X-RateLimit-Limit	Toda respuesta rate-limited (200 y 429)	Cuota total para este endpoint
X-RateLimit-Remaining	Toda respuesta rate-limited	Requests restantes en la ventana actual
Retry-After	Sólo en 429	Segundos a esperar antes de reintentar (igual al tamaño de ventana)

Sin `X-RateLimit-Reset`

La API no emite el header X-RateLimit-Reset. Para calcular cuándo se resetea la ventana en una respuesta 429, suma Retry-After segundos al instante actual del cliente.

Ejemplo de respuesta correcta:

HTTP/1.1 200 OK
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
Content-Type: application/json

Cuerpo del error 429

Cuando el bucket se agota, la respuesta es:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
Retry-After: 60
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60,
  "limit": 200,
  "remaining": 0,
  "timestamp": "2026-05-06T10:15:00Z"
}

El cuerpo de 429 no usa la envoltura estándar

A diferencia del resto de errores 4xx/5xx ({ timestamp, status, error, message, path } — ver Errores), el cuerpo de 429 usa los campos error, message, retryAfter, limit, remaining, timestamp. Manéjalo aparte si parseas errores genéricamente.

Backoff exponencial

Reintenta sólo en 429 y 5xx. Respeta Retry-After. Patrón recomendado: 1s, 2s, 4s, 8s con jitter, máximo 3-5 intentos.

using Polly;
using Polly.Extensions.Http;

var retryPolicy = HttpPolicyExtensions
  .HandleTransientHttpError()
  .OrResult(msg => (int)msg.StatusCode == 429)
  .WaitAndRetryAsync(
      retryCount: 3,
      sleepDurationProvider: (attempt, response, ctx) =>
      {
          if (response.Result?.Headers.RetryAfter?.Delta is TimeSpan retryAfter)
              return retryAfter;
          return TimeSpan.FromMilliseconds(
              Math.Pow(2, attempt) * 1000 + Random.Shared.Next(0, 250));
      },
      onRetryAsync: (_, _, _, _) => Task.CompletedTask);

var http = new HttpClient(new PolicyHttpMessageHandler(retryPolicy)
            { InnerHandler = new HttpClientHandler() });

Cuotas de plan vs rate limit

Son dos capas distintas. No las confundas:

Concepto	Qué controla	Dónde se ve	Granularidad
Rate limit (esta página)	Picos por minuto/cinco minutos	Headers X-RateLimit-*, error 429	Por endpoint, igual para todos
Cuota de plan	Volumen total mensual y catálogo máximo	GET /api/plugin/shops/me → maxProducts, productsCount, maxSearchesPerMonth, searchesThisMonth	Por shop, depende del plan

El plan tier (BASIC, GROWTH, PRO, ENTERPRISE) afecta a maxProducts y maxSearchesPerMonth retornados por /shops/me, no a los rate limits por endpoint, que son globales. Si tu integración necesita más volumen mensual, contacta soporte para subir de plan; los rate limits por endpoint no se elevan por plan.

Buenas prácticas

• Cachea /api/plugin/shops/me unos 5 min en el cliente como hace el plugin WordPress oficial; el endpoint sólo permite 60 req/min y productsCount/searchesThisMonth cambian lentamente.
• No abuses de widget-compare (10/min): cachea resultados o agrupa comparaciones.
• Sincroniza productos en lotes de hasta 500 (límite del endpoint sync) y espacia las llamadas; el bucket de sync permite 100 req/min, suficiente para catálogos grandes si paginan bien.
• No reintentes en 400, 401, 403, 404 ni 422 — son errores deterministas, reintentar no los corrige.
• Respeta Retry-After estrictamente. Ignorarlo puede llevar a abuso y bloqueo manual.

Próximas lecturas

• Errores — estructura completa del resto de errores 4xx/5xx.
• Shop API Key — generación, rotación y validación de Origin.
• Widget Token — TTL 24 h y renovación.