Que fait AppFolio Limites de Taux ?
Aperçu
L'API Stack d'AppFolio applique des limites de taux par partenaire pour protéger l'infrastructure de gestion immobilière partagée. Les opérations à fort volume telles que les importations de locataires en masse, les synchronisations de registres de loyers et les mises à jour par lots des ordres de travail peuvent rapidement épuiser les quotas. Les propriétaires de portefeuilles effectuant des synchronisations nocturnes de portefeuille sur des centaines d'unités doivent limiter soigneusement, surtout en fin de mois lorsque les renouvellements de baux et le traitement des paiements augmentent simultanément.
Prérequis
- Une limite par point de terminaison vérifiée à partir du contrat partenaire AppFolio actuel ou des en-têtes de réponse ; ne pas se fier à une valeur de taux générique pour les écritures de locataires.
- Des curseurs de lots persistés, des clés d'idempotence pour chaque écriture, et une politique d'opérateur pour suspendre les charges de travail de fin de mois ou autres sensibles à la sécurité.
- Un environnement de test (staging) et un propriétaire de budget de requêtes qui peut prouver les tentatives, le comportement
429et la gestion des écritures inconnues sans toucher aux locataires de production.
Instructions
- Sélectionnez le plafond du limiteur pour le point de terminaison spécifique et maintenez la concurrence en dessous de la plus petite limite applicable du portefeuille ou du partenaire.
- Acquérez un jeton avant chaque requête, respectez
Retry-After, et plafonnez les tentatives avec jitter pour les défaillances transitoires du fournisseur. - Traitez les écritures à partir d'un curseur persisté avec des clés d'idempotence ; ne rejouez jamais une création de locataire simplement parce que la réponse a été perdue.
- Suspendre et escalader les lots qui épuisent le budget de tentatives, rencontrent une fenêtre de maintenance, ou ont un résultat d'écriture inconnu.
Référence des Limites de Taux
| Point de terminaison | Limite | Fenêtre | Portée |
|---|---|---|---|
| Liste/obtenir propriétés | 120 req | 1 minute | Par clé partenaire |
| Créer/mettre à jour locataire | 30 req | 1 minute | Par clé partenaire |
| Ordres de travail | 60 req | 1 minute | Par clé partenaire |
| Exportation de données en masse | 5 req | 1 heure | Par clé partenaire |
| Enregistrement de webhooks | 10 req | 1 minute | Par clé partenaire |
Implémentation du Limiteur de Taux
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;
}
// Attend jusqu'à ce que le prochain jeton soit disponible ; aucune requête ultérieure n'est nécessaire pour
// réveiller cet appelant.
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); // configurer selon le contrat du point de terminaison
Stratégie de Tentatives
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");
}
Traitement par Lots
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;
}
Gestion des Erreurs
| Problème | Cause | Correctif |
|---|---|---|
| 429 Trop de Requêtes | Limite de taux du partenaire dépassée | Backoff en utilisant l'en-tête Retry-After |
| 403 sur export en masse | Plafond d'export horaire atteint | Mettre en file d'attente les exports avec un espacement de 15 minutes |
| Timeout sur liste de propriétés | Grand portefeuille (500+ unités) | Paginer avec per_page=50 |
| 409 Conflit sur mise à jour de locataire | Écriture simultanée sur le même locataire | Réessayer avec un nouvel ETag |
| 503 pendant maintenance | Fenêtre nocturne planifiée (2-4 AM PT) | Ignorer les requêtes, réessayer après la fenêtre |
Résultats
- Un limiteur auto-planifié, spécifique au point de terminaison, qui ne peut pas bloquer le travail en file d'attente
- Des résultats de tentatives bornés avec preuve de
Retry-Afteret données d'échec expurgées - Une décision de lot persistée : terminée, mise en pause pour une tentative ultérieure, ou mise en quarantaine pour la réconciliation de l'opérateur
Exemples
Pour un lot de mise à jour de locataire en environnement de test, configurez le limiteur en dessous du plafond documenté d'écriture de locataire, traitez un enregistrement à la fois avec des clés d'idempotence, et préservez le curseur après chaque résultat confirmé. Provoquez une 429 pour prouver que les appelants attendent et reprennent sans requête supplémentaire, puis provoquez une réponse perdue pour prouver que l'enregistrement est mis en quarantaine plutôt que rejoué aveuglément. Si les en-têtes de taux entrent en conflit avec le plafond configuré, si les tentatives s'épuisent ou si la maintenance commence, mettez le lot en pause et remettez le curseur au propriétaire.
Ressources
Prochaines Étapes
Voir appfolio-performance-tuning.