Qué se rompe primero cuando se ignoran los límites de la API
Una empresa que ejecuta tres integraciones simultáneamente —sincronización nocturna de ERP, webhook de un sistema de pagos y un panel externo que extrae datos cada cinco minutos— no falla gradualmente. Funciona perfectamente hasta que cruza un umbral, y entonces cada llamada adicional a la API es rechazada con el código REQUEST_LIMIT_EXCEEDED hasta el restablecimiento diario. No hay una alerta temprana incorporada que lo impida de antemano; solo existe un panel que se puede consultar, si alguien ha configurado un proceso para hacerlo.
Este tipo de fallo es diferente de la mayoría de los fallos en los proyectos de Salesforce porque no depende de un código deficiente o de un diseño defectuoso. Depende de la acumulación: una nueva integración siempre se construye frente al estado actual, sin verificar cuánto del presupuesto diario ya ha sido consumido por los procesos existentes. El resultado es que la quinta integración "rompe" las cuatro anteriores, a pesar de que ninguna de ellas ha cambiado.
Mapa de los límites relevantes en la práctica
No todos los límites existentes en Salesforce son igualmente importantes para el diseño de integraciones. Aquellos que realmente determinan la arquitectura son:
| Tipo de límite | Lo que mide | A quién afecta primero |
|---|---|---|
| Solicitudes API diarias | Total de llamadas REST/SOAP en 24 horas | Cualquier integración síncrona de alta frecuencia |
| Lotes de Bulk API | Número de lotes abiertos/diarios | Procesos de lotes nocturnos que ingieren datos históricos |
| Solicitudes concurrentes de larga duración | Llamadas concurrentes que duran más de 20 segundos | Informes pesados o Apex síncrono complejo |
| Entrega de Platform Events | Volumen de eventos por día por suscriptor | Arquitecturas basadas en eventos entre Salesforce y sistemas externos |
| Filas SOQL por transacción | Filas recuperadas en una única transacción (50.000) | Lógica Apex que ejecuta consultas dentro de un bucle |
Esta tabla no es una documentación genérica, es un orden de prioridades. Una organización que planea una nueva integración debe revisar primero las dos primeras filas, ya que son las que realmente se bloquean en producción. El resto de los límites afectan principalmente al rendimiento, no a la disponibilidad.
Presupuesto de llamadas: cómo construirlo correctamente
La herramienta principal para evitar bloqueos no es la monitorización a posteriori, sino un presupuesto predefinido para cada consumidor de API. El principio: cada sistema externo, cada Usuario de Integración y cada proceso programado recibe una asignación definida de la cuota total, y no "cuanto sea necesario".
La construcción del presupuesto incluye tres pasos:
- Mapeo de consumidores: Una lista de cada proceso que llama a la API: integraciones externas, Scheduled Apex, Data Loader manual, herramientas de BI. Cada uno tiene un Usuario de Integración separado para poder aislar el consumo en Event Monitoring.
- Cálculo de la carga según el volumen de negocio, no según la suposición: ¿Cuántos registros se mueven por día, cuántas llamadas se requieren por registro (incluida la recuperación de listas relacionadas), y qué sucede en el pico (fin de trimestre, Black Friday, cierre de mes)?
- Asignación de reserva: No se distribuye el 100% de la cuota entre los procesos existentes. Se deja un 15%-20% como reserva para procesos de emergencia, informes ad hoc y mantenimiento; de lo contrario, cualquier pequeña adición empuja a la organización a exceder los límites.
Aquellos que deseen profundizar en el diseño de la capa que gestiona este presupuesto a nivel de plataforma deberían consultar la Guía de Arquitectura de CRM, donde se presenta la división entre la capa de integración y la capa de negocio.
REST vs. Bulk: cuándo la transición vale la pena
El error más común es usar la API REST regular para un alto volumen de tráfico de datos, porque es lo primero que se construye y funciona en una prueba de concepto (PoC). El problema aparece cuando el volumen crece: REST cuenta cada solicitud (hasta 200 registros en Composite) como una llamada separada contra la cuota, mientras que Bulk API 2.0 ejecuta lotes de hasta 10.000 registros y se cuenta con un costo significativamente menor por registro.
Una regla práctica general: si un solo proceso actualiza más de aproximadamente 2.000 registros en una ejecución, la transición a Bulk API casi siempre vale la pena, incluso si esto implica cambiar el código del consumidor para trabajar de forma asíncrona con sondeo sobre el estado del trabajo en lugar de una respuesta inmediata. El costo es una latencia más alta (minutos en lugar de segundos), por lo que Bulk no es adecuado para procesos que requieren una decisión en tiempo real, como la verificación de inventario antes de aprobar un pedido.
Backoff y Retry: prevención del auto-ahogo
Cuando una llamada a la API falla debido a un bloqueo de límite, la respuesta instintiva de la mayoría de los equipos es volver a intentarlo de inmediato. Este es precisamente el comportamiento que convierte un bloqueo temporal en un fallo persistente: si diez procesos lo intentan de nuevo al mismo tiempo, empujan al sistema más profundamente en el bloqueo en lugar de permitir que se recupere.
Un mecanismo de backoff correcto requiere tres componentes juntos:
- Backoff exponencial: El tiempo de espera entre intentos crece exponencialmente (por ejemplo, 2, 4, 8, 16 segundos), no permanece constante.
- Jitter: Una pequeña adición aleatoria al tiempo de espera, para que los procesos paralelos no lo intenten de nuevo en el mismo segundo exacto y creen una nueva ola de carga.
- Circuit Breaker: Después de una serie de fallas consecutivas (por ejemplo, cinco), el proceso deja de intentarlo por completo durante un período de tiempo fijo y reporta al monitoreo, en lugar de seguir "golpeando la puerta".
Sin un Circuit Breaker, un proceso que se ejecuta cada cinco minutos y falla consistentemente seguirá intentándolo cien veces al día y consumiendo la cuota solo en fallas; esto es exactamente lo contrario de lo que el mecanismo debería prevenir. Se puede encontrar más información sobre el manejo de errores a nivel de integración en Manejo de Errores de Integración en Salesforce.
Escenario: Comercio minorista con tres puntos de integración
Supongamos una cadena minorista mediana, con aproximadamente 40 sucursales, que opera Salesforce Service Cloud frente a un sistema POS y un sistema ERP para inventario. Tres integraciones activas: sincronización de inventario cada 15 minutos desde el ERP (aproximadamente 8.000 SKUs), un webhook desde el POS por cada transacción fallida (aproximadamente 300 por día), y un panel externo para Power BI que extrae datos de servicio cada hora.
En el mes en que la cadena agregó un nuevo programa de lealtad, entró en juego una cuarta integración: verificación de puntos de crédito en tiempo real contra Salesforce desde cada caja, aproximadamente 6.000 llamadas diarias adicionales. En dos semanas, la sincronización de inventario comenzó a fallar entre las 14:00 y las 15:00, la hora pico de las cajas. El equipo verificó primero el ERP y pensó que el problema estaba allí, pero el registro de Salesforce mostró REQUEST_LIMIT_EXCEEDED exactamente en ese período.
La solución no fue comprar cuota adicional, sino cambiar el orden de las prioridades: la verificación de puntos de crédito pasó a usar Platform Cache para resultados que no cambian con frecuencia, lo que redujo las llamadas en aproximadamente un 70%, y la sincronización de inventario pasó de REST a Bulk API con una ejecución cada 30 minutos en lugar de 15. El resultado: la misma cobertura de negocio, un consumo de cuota un 45% menor y una reserva real para el próximo crecimiento.
Riesgos y acciones preventivas específicas
| Riesgo | Cómo se manifiesta en la práctica | Acción preventiva |
|---|---|---|
| Nueva integración no probada contra el presupuesto existente | El bloqueo aparece solo después del lanzamiento a producción | Requisito de Revisión de Capacidad para cada nueva integración antes de la puesta en marcha |
| Reintento sin Backoff | El bloqueo temporal se convierte en un fallo de horas | Backoff Exponencial con Jitter y Circuit Breaker en cada consumidor de API |
| Uso de REST para grandes volúmenes | Un solo proceso consume decenas de porcentajes de la cuota diaria | Transición a Bulk API por encima de un umbral de volumen predefinido |
| Ausencia de Usuarios de Integración separados | Imposible saber qué integración consume la cuota | Usuario de Integración dedicado para cada sistema externo, monitoreado por separado |
| Falta de reserva en el presupuesto | Cualquier pequeña adición empuja a exceder el límite | Asignación del 15%-20% de la cuota como reserva permanente no asignada para procesos diarios |
Lista de verificación antes de añadir una nueva integración
- ☐ Se conoce el porcentaje actual de consumo de la cuota diaria, por Usuario de Integración.
- ☐ Se ha verificado el volumen pico (no el volumen promedio) de la nueva integración.
- ☐ Se ha decidido entre REST y Bulk API según el umbral de volumen, no según la conveniencia de desarrollo.
- ☐ Existe un mecanismo de Backoff con Jitter y Circuit Breaker en el código del consumidor.
- ☐ Se ha configurado una alerta cuando el consumo de la cuota diaria supera el 70%.
- ☐ Se ha evaluado el posible uso de Platform Cache para reducir llamadas repetidas.
- ☐ Existe una reserva del 15%-20% de la cuota que no ha sido asignada previamente.
- ☐ Se ha definido un Propietario operativo que recibe la alerta y no solo un registro técnico.
Cómo monitorear esto de forma continua
La medición fiable requiere una combinación de tres fuentes: Event Monitoring (o Shield Event Monitoring) para el consumo real de API por usuario, Apex Limits dentro del propio código (Limits.getLimitApiRequests()) para pruebas locales en tiempo de ejecución, y el Panel incorporado en Información de la Empresa que muestra el consumo frente a la cuota a nivel de organización. Ninguna de las tres es suficiente por sí sola: la primera muestra tendencias, la segunda previene fallos dentro de un proceso individual y la tercera sirve como instantánea diaria para el equipo de operaciones.
Una métrica que vale la pena seguir a lo largo del tiempo no es solo "cuánto se consume", sino "cuál es la tasa de crecimiento mensual del consumo", ya que esto permite predecir cuándo la organización alcanzará el límite, en lugar de reaccionar después de que el bloqueo ya haya ocurrido. Cuando hay varios sistemas dependientes entre sí, también vale la pena examinar el patrón de integración general con la integración de Salesforce con sistemas ERP, y la cuestión de la implementación, Flow frente a Apex, que también afecta la eficiencia de las llamadas, en Salesforce Flow o Apex.
Resumen
Los límites de la API de Salesforce no son un problema que se resuelve en el momento en que se descubre; son una variable que debe formar parte de cada decisión de integración desde el primer día. Un presupuesto de llamadas documentado por Usuario de Integración, una elección consciente entre REST y Bulk según el volumen, y un mecanismo de backoff que evita el auto-ahogo, estos tres juntos son lo que distingue a una organización que descubre el problema cuando ya está bloqueada, de una organización que lo ve acercarse con un mes de anticipación y actúa a tiempo.