Leadde Logo

Entendiendo los Límites de Tasa de API

Una guía práctica que explica qué son los límites de tasa de API, por qué se implementan, los errores comunes al reintentar y patrones efectivos como el 'exponential backoff'.
LPor Leadde Actualizado 22 de agosto de 2026

Cómo un Límite de Tasa Determina si tu Solicitud se Ejecuta

Un límite de tasa establece un tope en la cantidad de solicitudes que un cliente puede enviar en una ventana y devuelve un 429 una vez que se supera ese tope. El límite existe para evitar que un cliente consuma la capacidad que pertenece a todos, por lo que la respuesta correcta es reducir la velocidad en lugar de enviar la misma solicitud de nuevo de inmediato.

Reintentar de inmediato es exactamente lo que hacen la mayoría de las primeras integraciones, y esto convierte un rechazo temporal en uno sostenido. El cliente alcanza el límite, reintenta, extiende la ventana de medición y termina siendo ralentizado por mucho más tiempo de lo que la ráfaga original requería, generalmente mientras un desarrollador concluye que la API no es confiable. Se excluye a propósito la configuración de tu propio límite: los umbrales por nivel, las asignaciones de ráfaga y los puntos finales con límites más estrictos pertenecen a la documentación versionada en lugar de a un video que envejece.

La plantilla sigue una solicitud a través de ocho escenas: una sobre por qué existen los límites, una sobre la ventana y cómo se cuenta, una sobre lo que contiene una respuesta 429, dos sobre el 'backoff' y por qué el retraso debe aumentar, una sobre el 'jitter' y el 'thundering herd', una sobre la lectura de los encabezados de límite de tasa, y una sobre cómo diseñar para que el límite rara vez se alcance.

Cómo Explicar el 'Backoff' en Menos de Dos Minutos

La educación para desarrolladores compite con la documentación que el espectador ya tiene abierta. Cualquier cosa que repita la página de referencia se cierra en veinte segundos, por lo que el módulo debe transmitir lo único que la documentación comunica mal: el patrón de fallo en lugar del parámetro.

Muestra la tormenta de reintentos antes de la solución

Muestra la tormenta de reintentos antes de la solución

Un cliente que reintenta cada 200 milisegundos contra un límite que ya ha superado es todo el problema, visible en una sola escena. El 'backoff' llega entonces como la solución obvia, no como una recomendación.

Haz explícita la duplicación

Un segundo, dos, cuatro, ocho. Indicar la progresión es más rápido que definir el 'exponential backoff' y es lo que un desarrollador realmente implementa.

Dale al 'jitter' su propio momento

Sin aleatorización, cada cliente ralentizado reintenta simultáneamente y el intento de recuperación se convierte en la siguiente interrupción. Esta es la parte que la mayoría de las integraciones omiten y la razón por la que existe el módulo.

Señala los encabezados en lugar de los números

Los límites cambian; los encabezados que los informan no. Enseñar al cliente a leer lo que se le indica es mejor que codificar un umbral que será incorrecto el próximo trimestre.

Extráelo de la documentación de API que ya publicas

Sube la documentación de la API, la guía de integración enviada a los socios o los tickets de soporte del último 'onboarding' — 200 MB máximo, en formato PDF, DOC, DOCX, PPTX o TXT. Las escenas quedan disponibles para edición, dejando el documento original intacto.

Alineándolo con tu Propia API

Usa tus propios nombres de encabezado en pantalla

Usa tus propios nombres de encabezado en pantalla

La nomenclatura de los encabezados difiere entre plataformas, y un desarrollador al que se le muestra un ejemplo genérico aún tiene que buscar los tuyos. Poner los nombres reales en la escena elimina ese paso.

Di qué sucede después de repetidas infracciones

Di qué sucede después de repetidas infracciones

Algunas plataformas aplican throttling, otras suspenden claves, otras alertan a un humano. Ser explícito sobre la consecuencia cambia la seriedad con la que un socio trata la orientación.

Estiliza los subtítulos para términos que deben leerse exactamente

Estiliza los subtítulos para términos que deben leerse exactamente

Los códigos de estado, los nombres de los encabezados y los valores de los parámetros se malinterpretan fácilmente al oírlos y se leen de forma fiable. Elige entre los nueve estilos de subtítulos, mantén el mismo en toda la serie para desarrolladores y asegúrate de que los términos de código sigan siendo legibles en tamaños pequeños.

Preguntas Frecuentes sobre Límites de Tasa de API

Un límite de tasa rige la velocidad durante una ventana corta, generalmente segundos o un minuto, y es recuperable esperando. Una cuota rige el volumen total durante un período de facturación y no lo es. Confundirlos lleva a los clientes a retroceder cuando necesitan solicitar un aumento.

Lee el valor 'retry-after' si se proporciona, espera al menos ese tiempo y luego reintenta con un retraso que aumenta en cada fallo posterior. Reintentar de inmediato o en un intervalo corto fijo extiende el throttling en lugar de eliminarlo.

Los nombres de 'endpoint' están bien y hacen que el módulo sea más útil. Las claves y los tokens no lo están, incluidos los caducados, porque un video de capacitación circula fuera del socio para el que fue creado y vive mucho más tiempo que la credencial.

Porque la solicitud fallida sigue contando contra la ventana en la mayoría de las implementaciones. Cada reintento empuja al cliente más allá del límite, por lo que el tiempo de espera necesario para eliminarlo aumenta con cada intento de evitar esperar.

Aplica Throttling Antes de que lo Haga Producción

Pasa la documentación de la API que ya publicas por él, luego ajusta las escenas antes de la próxima integración con un socio.

avatar

Empieza con esta plantilla. Termina con un video listo para compartir.

Añade tu guía de incorporación o páginas del centro de ayuda y genera un borrador editable en minutos.