Límites de Tasa de AppFolio
Resumen
La API Stack de AppFolio impone límites de tasa por socio para proteger la infraestructura compartida de gestión de propiedades. Las operaciones de alto volumen, como importaciones masivas de inquilinos, sincronizaciones de rentas y actualizaciones por lotes de órdenes de trabajo, pueden agotar rápidamente las cuotas. Los administradores de propiedades que ejecutan sincronizaciones de cartera nocturnas a través de cientos de unidades deben limitar cuidadosamente, especialmente durante fin de mes cuando las renovaciones de arrendamiento y el procesamiento de pagos aumentan simultáneamente.
Requisitos Previos
- Un límite verificado por punto final del contrato actual de socio de AppFolio o de los encabezados de respuesta; no confíes en un valor genérico de tasa para escrituras de inquilinos.
- Cursores de lote persistidos, claves de idempotencia para cada escritura y una política del operador para pausar cargas de trabajo de fin de mes u otras sensibles a la seguridad.
- Un fixture de staging y un propietario del presupuesto de solicitudes que pueda probar reintentos, comportamiento de "429" y manejo de escrituras desconocidas sin tocar inquilinos en producción.
Instrucciones
- Selecciona el techo del limitador para el punto final específico y mantén la concurrencia por debajo del límite de cartera o socio aplicable más pequeño.
- Adquiere un token antes de cada solicitud, respeta
Retry-Aftery limita los reintentos con jitter para fallos transitorios del proveedor. - Procesa escrituras desde un cursor persistido con claves de idempotencia; nunca reproduzcas una creación de inquilino solo porque se perdió la respuesta.
- Pausa y escala lotes que agoten el presupuesto de reintentos, encuentren una ventana de mantenimiento o tengan un resultado de escritura desconocido.
Referencia de Límites de Tasa
| Punto final | Límite | Ventana | Ámbito |
|---|---|---|---|
| Lista/obtén propiedades | 120 solicitudes | 1 minuto | Por clave de socio |
| Crear/actualizar inquilino | 30 solicitudes | 1 minuto | Por clave de socio |
| Órdenes de trabajo | 60 solicitudes | 1 minuto | Por clave de socio |
| Exportación masiva de datos | 5 solicitudes | 1 hora | Por clave de socio |
| Registro de webhooks | 10 solicitudes | 1 minuto | Por clave de socio |
Implementación del Limitador de Tasa
class AppFolioRateLimiter {
private tokens: number;
private lastRefill: number;
private readonly maxTokens: number;
private readonly refillRate: number; // tokens per ms
constructor(maxPerMinute: number) {
this.maxTokens = maxPerMinute;
this.tokens = maxPerMinute;
this.lastRefill = Date.now();
this.refillRate = maxPerMinute / 60_000;
}
async acquire(): Promise<void> {
for (;;) {
this.refill();
if (this.tokens >= 1) {
this.tokens -= 1;
return;
}
// Wait until the next token is available; no later request is needed to
// wake this caller.
const waitMs = Math.max(1, Math.ceil((1 - this.tokens) / this.refillRate));
await new Promise(resolve => setTimeout(resolve, waitMs));
}
}
private refill() {
const now = Date.now();
this.tokens = Math.min(this.maxTokens, this.tokens + (now - this.lastRefill) * this.refillRate);
this.lastRefill = now;
}
}
const limiter = new AppFolioRateLimiter(25); // configure per endpoint contract
Estrategia de Reintentos
async function appfolioRetry<T>(fn: () => Promise<Response>, maxRetries = 4): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
await limiter.acquire();
const res = await fn();
if (res.ok) return res.json();
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get("Retry-After") || "10", 10);
const delay = retryAfter * 1000 + Math.random() * 2000;
await new Promise(r => setTimeout(r, delay));
continue;
}
if (res.status >= 500 && attempt < maxRetries) {
await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
continue;
}
throw new Error(`AppFolio API ${res.status}: ${await res.text()}`);
}
throw new Error("Max retries exceeded");
}
Procesamiento por Lotes
async function batchSyncTenants(tenants: any[], batchSize = 25) {
const results: any[] = [];
for (let i = 0; i < tenants.length; i += batchSize) {
const batch = tenants.slice(i, i + batchSize);
const batchResults = await Promise.all(
batch.map(t => appfolioRetry(() =>
fetch(`${BASE}/api/v1/tenants`, {
method: "POST", headers, body: JSON.stringify(t),
})
))
);
results.push(...batchResults);
if (i + batchSize < tenants.length) await new Promise(r => setTimeout(r, 2000));
}
return results;
}
Manejo de Errores
| Problema | Causa | Solución |
|---|---|---|
| 429 Demasiadas solicitudes | Límite de tasa de socio excedido | Retroceso usando el encabezado Retry-After |
| 403 en exportación masiva | Límite de exportación por hora alcanzado | Poner en cola exportaciones con espacio de 15 minutos |
| Tiempo de espera en lista de propiedades | Cartera grande (500+ unidades) | Paginar con per_page=50 |
| 409 Conflicto en actualización de inquilino | Escritura concurrente al mismo inquilino | Reintentar con nuevo ETag |
| 503 durante mantenimiento | Ventana nocturna programada (2-4 AM PT) | Omitir solicitudes, reintentar después de la ventana |
Salida
- Un limitador auto-programable y específico por punto final que no puede dejar trabajo en cola
- Resultados de reintentos acotados con evidencia de
Retry-Aftery datos de fallo redactados - Una decisión de lote persistida: completada, pausada para reintento posterior, o en cuarentena para conciliación del operador
Ejemplos
Para un lote de actualización de inquilinos en sandbox, configura el limitador por debajo del techo documentado de escritura de inquilinos, procesa un registro a la vez con claves de idempotencia y preserva el cursor después de cada resultado confirmado. Induce un 429 para probar que los llamados esperan y reanudan sin una solicitud adicional, luego induce una respuesta perdida para probar que el registro se pone en cuarentena en lugar de reproducirse ciegamente. Si los encabezados de tasa entran en conflicto con el techo configurado, los reintentos se agotan o comienza el mantenimiento, pausa el lote y entrega el cursor al propietario.
Recursos
Próximos Pasos
Consulta appfolio-performance-tuning.