Límites de velocidad
Un límite de velocidad define el número máximo de solicitudes que una aplicación puede realizar a la API dentro de un período de tiempo determinado. Este mecanismo es fundamental para mantener la salud general y la confiabilidad de los servicios.
Por qué usamos límites de velocidad
- Evita que un solo cliente sature los servidores con solicitudes excesivas.
- Garantiza tiempos de respuesta consistentes y predecibles para todos los clientes.
- Protege los servicios de backend ante picos de tráfico inesperados.
- Mantiene un patrón de carga estable y controlado en la infraestructura.
- Refuerza la defensa contra intentos de ataque, como la fuerza bruta.
- Mitiga el riesgo de denegación de servicio distribuida (DDoS).
- Reduce el impacto causado por integraciones mal implementadas.
- Limita el daño potencial derivado de credenciales de API comprometidas.
- Garantiza un acceso equitativo a los recursos de la API para todos los clientes.
- Evita que el uso abusivo de algunos degrade la experiencia de otros usuarios.
- Permite priorizar el tráfico según criterios y necesidades de negocio.
- Fomenta prácticas de consumo de la API más eficientes y sostenibles.
Cómo funcionan los límites de velocidad
Cada llamada a la API cuenta para el límite de solicitudes por segundo permitido. El valor predeterminado es 10 RPS por tenant. Cuando se supera el límite, la API devuelve HTTP 429 Too Many Requests.
Los límites exactos se configuran por tenant. Contacte a su equipo de Onboarding para confirmar los límites aplicados a su cuenta antes de dimensionar integraciones de alto rendimiento.
Manejo de errores 429
Si su operación tendrá un incremento en el volumen de solicitudes (temporal o permanente), notifique al equipo de Unico para aumentar el límite de velocidad de su entorno. Esta solicitud debe realizarse antes de que el volumen aumente realmente, para evitar que su aplicación quede inoperativa.
- Audite su código para identificar patrones ineficientes de uso de la API.
- Verifique la existencia de bucles no intencionados o llamadas a la API redundantes.
- Distribuya las solicitudes de forma más uniforme a lo largo del tiempo en lugar de enviarlas en ráfagas grandes.
- Almacene en caché los datos de acceso frecuente que rara vez cambian.
- Use el token de acceso OAuth2 durante su TTL completo de 1 hora — no llame a
POST /oauth2/tokenpor cada solicitud. - Implemente estrategias adecuadas de invalidación de caché.
Suscríbase a Webhooks y Eventos para PROCESS_STATE_FINISHED en lugar de hacer polling a GET /client/v1/process/\{id\}. Un bucle de polling puede agotar fácilmente el presupuesto de GET-process en tráfico alto.
Qué ocurre cuando se alcanza el límite
La plataforma devuelve:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
| Encabezado | Significado |
|---|---|
Retry-After | Número de segundos que debe esperar antes de reintentar. Respételo. |
Si Retry-After no está presente, utilice backoff exponencial (1s, 2s, 4s, 8s, …) con un máximo de 60s.
Consideraciones de concurrencia
Los límites de velocidad restringen las solicitudes por minuto, pero la plataforma también tiene límites de concurrencia a nivel de infraestructura. Incluso si tiene presupuesto para 100 solicitudes/minuto, enviarlas todas en el mismo segundo tiene más probabilidades de ser rechazado que distribuirlas a lo largo del minuto.
Para integraciones de alto rendimiento, apunte a un RPS constante en lugar de ráfagas.
Entrega de webhooks de Magic Link
Trully tiene sus propias cuotas de entrega para Webhook V2. Se espera que el servidor de webhooks responda en 1 minuto; las respuestas más lentas se descartan (el proceso del usuario no se ve afectado). Para un procesamiento consistente, acuse recibo del webhook rápidamente y procéselo de forma asíncrona.
¿Qué sigue?
- Autenticación — estrategia de caché de tokens.
- Webhooks y Eventos — reemplazar el polling con push.
- Códigos de error > Política de reintentos — cuándo (y cuándo no) reintentar.