Límites de velocidad

Los límites se aplican por clave con una ventana fija de 60 segundos que se reinicia al llegar al límite. El valor predeterminado es 60 solicitudes por minuto y clave; pueden negociarse límites mayores para Production.

Cabeceras de respuesta

Cada respuesta incluye el estado actual del límite.

Al superar el límite, se devuelve HTTP 429 con error.code = rate_limit_exceeded y una cabecera Retry-After que indica los segundos de espera.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782604860
Retry-After: 12

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Se superó el límite de solicitudes.",
    "request_id": "req_..."
  }
}

Rutas públicas sin autenticación

Las rutas públicas no tienen clave y se limitan a 20 solicitudes por minuto e IP, con la misma ventana, cabeceras y contrato 429 + Retry-After. Se aplica a creación, estado y reclamación de solicitudes (POST /v1/partner-applications*) y a POST /v1/api-keys/bootstrap, reduciendo spam y fuerza bruta.

Pautas de reintento

• Respete Retry-After. Espere los segundos indicados antes de reintentar y no sature el endpoint.
• Use backoff exponencial con jitter para respuestas 429 y 5xx repetidas.
• Limite de forma proactiva. Controle X-RateLimit-Remaining y reduzca el ritmo antes de llegar a cero.
• Agrupe cuando sea posible. Use POST /events/batch para hasta 500 eventos en vez de muchas llamadas POST /events (API de eventos).
• Separe claves por carga. Como el límite es por clave, use claves distintas para ingesta masiva y llamadas interactivas.
• Los reintentos son seguros en operaciones idempotentes compatibles. Los eventos se deduplican por event_id; crear tokens, solicitudes de licencia y rotar claves acepta X-NU-Request-Id. Un reintento completado en 24 horas reproduce el resultado; uno aún en curso devuelve 409 conflict.

El tratamiento de límites en Production forma parte de la Lista de Production.