AppFolio-Ratenlimits
Übersicht
Die AppFolio Stack-API setzt partnerabhängige Ratenlimits durch, um die gemeinsam genutzte Infrastruktur für die Immobilienverwaltung zu schützen. Hochvolumige Vorgänge wie Massen-Mieterimporte, Mietspiegel-Synchronisationen und Batch-Updates von Arbeitsaufträgen können die Kontingente schnell erschöpfen. Property Manager, die nächtliche Portfolio-Synchronisationen über Hunderte von Einheiten hinweg durchführen, müssen die Drosselung sorgfältig justieren, insbesondere am Monatsende, wenn Mietverlängerungen und Zahlungsabwicklungen gleichzeitig ansteigen.
Voraussetzungen
- Ein verifiziertes, endpointspezifisches Limit aus dem aktuellen AppFolio-Partnervertrag oder den Antwortheadern; verlassen Sie sich nicht auf einen generischen Ratenwert für Mieter-Schreibvorgänge.
- Persistierte Batch-Cursor, Idempotenzschlüssel für jeden Schreibvorgang und eine Betriebsrichtlinie für das Anhalten von workloads, die sicherheitskritisch sind (z. B. am Monatsende).
- Eine Testumgebung und ein Request-Budget-Verantwortlicher, die nachweisen können, dass Wiederholungen,
429-Verhalten und unbekannte Schreibvorgänge ohne Beeinträchtigung von Produktionsmandanten behandelt werden.
Anleitung
- Wählen Sie die Begrenzungsgrenze für den jeweiligen Endpunkt und halten Sie die Parallelität unter dem kleinsten anwendbaren Portfolio- oder Partnerlimit.
- Holen Sie vor jeder Anfrage ein Token ein, beachten Sie
Retry-After, und begrenzen Sie Wiederholungen mit Jitter bei vorübergehenden Provider-Fehlern. - Verarbeiten Sie Schreibvorgänge von einem persistierten Cursor aus mit Idempotenzschlüsseln; wiederholen Sie niemals eine Mietererstellung nur, weil die Antwort verloren ging.
- Stoppen Sie Batches, die das Wiederholungsbudget erschöpfen, in ein Wartungsfenster fallen oder ein unbekanntes Schreibergebnis haben, und eskalieren Sie sie.
Referenz zu Ratenlimits
| Endpunkt | Limit | Fenster | Geltungsbereich |
|---|---|---|---|
| Eigenschaften auflisten/abrufen | 120 Anfragen | 1 Minute | Pro Partner-Schlüssel |
| Mieter erstellen/aktualisieren | 30 Anfragen | 1 Minute | Pro Partner-Schlüssel |
| Arbeitsaufträge | 60 Anfragen | 1 Minute | Pro Partner-Schlüssel |
| Massendatenexport | 5 Anfragen | 1 Stunde | Pro Partner-Schlüssel |
| Webhook-Registrierung | 10 Anfragen | 1 Minute | Pro Partner-Schlüssel |
Implementierung des Ratenbegrenzers
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;
}
// Warten, bis das nächste Token verfügbar ist; es ist keine spätere Anfrage
// erforderlich, um diesen Aufrufer aufzuwecken.
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); // gemäß Endpunktvertrag konfigurieren
Wiederholungsstrategie
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("Maximale Anzahl von Wiederholungen überschritten");
}
Batch-Verarbeitung
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;
}
Fehlerbehandlung
| Problem | Ursache | Lösung |
|---|---|---|
| 429 Too Many Requests | Partner-Ratenlimit überschritten | Backoff mithilfe des Retry-After-Headers |
| 403 bei Bulk-Export | Stündliches Exportlimit erreicht | Exporte im 15-Minuten-Abstand in die Warteschlange einreihen |
| Timeout bei Eigenschaftsliste | Großes Portfolio (500+ Einheiten) | Paginierung mit per_page=50 |
| 409 Conflict bei Mieteraktualisierung | Gleichzeitiger Schreibvorgang auf denselben Mieter | Wiederholung mit aktuellem ETag |
| 503 während Wartungsarbeiten | Geplantes nächtliches Wartungsfenster (2-4 Uhr PT) | Anfragen auslassen, nach dem Fenster wiederholen |
Ausgabe
- Ein selbstplanender, endpointspezifischer Begrenzer, der eingeplante Arbeiten nicht blockieren kann
- Begrenzte Wiederholungsergebnisse mit
Retry-After-Nachweis und geschwärzten Fehlerdaten - Eine persistierte Batch-Entscheidung: abgeschlossen, zur späteren Wiederholung angehalten oder für die Operator-Abstimmung unter Quarantäne gestellt
Beispiele
Stellen Sie für einen Sandbox-Mieteraktualisierungs-Batch den Begrenzer unter dem dokumentierten Mieter-Schreib-Limit ein, verarbeiten Sie einen Datensatz nach dem anderen mit Idempotenzschlüsseln und bewahren Sie den Cursor nach jedem bestätigten Ergebnis auf. Lösen Sie einen 429-Fehler aus, um nachzuweisen, dass Aufrufer warten und ohne zusätzliche Anfrage fortfahren. Lösen Sie dann eine verlorene Antwort aus, um zu beweisen, dass der Datensatz unter Quarantäne gestellt wird und nicht blind wiederholt wird. Wenn die Raten-Header mit dem konfigurierten Limit kollidieren, Wiederholungen ausgeschöpft werden oder Wartungsarbeiten beginnen, stoppen Sie den Batch und übergeben Sie den Cursor an den Verantwortlichen.
Ressourcen
Nächste Schritte
Siehe appfolio-performance-tuning.