AppFolio レート制限
概要
AppFolioのStack APIは、共有プロパティ管理インフラストラクチャを保護するためにパートナーごとのレート制限を適用しています。テナントの一括インポート、家賃収入の同期、作業指示書のバッチ更新といった大量処理は、クォータを急速に消費する可能性があります。数百戸のポートフォリオで夜間に同期を実行するプロパティマネージャーは、特に月末にリース更新と支払い処理が同時に増加する時期に、慎重なスロットリングが必要です。
前提条件
- 現在のAppFolioパートナー契約またはレスポンスヘッダーからの、エンドポイントごとの検証済み制限値。テナント書き込みには汎用的なレート値を使用しないでください。
- 永続化されたバッチカーソル、すべての書き込みに対する冪等性キー、および月末などの安全重視ワークロードを一時停止するためのオペレーターポリシー。
- リトライ、
429動作、および不明な書き込み処理を本番テナントに影響を与えずに検証できるステージングフィクスチャとリクエストバジェット責任者。
手順
- 特定のエンドポイントのリミッター上限を選択し、同時実行数を該当する最小のポートフォリオまたはパートナー制限以下に保ちます。
- 各リクエストの前にトークンを取得し、
Retry-Afterを尊重し、一時的なプロバイダー障害に対してはジッター付きでリトライを制限します。 - 永続化されたカーソルから冪等性キーを使用して書き込みを処理します。レスポンスが失われたからといってテナント作成を再実行しないでください。
- リトライバジェットを使い果たした場合、メンテナンスウィンドウに達した場合、または書き込み結果が不明な場合は、バッチを一時停止してエスカレーションします。
レート制限リファレンス
| エンドポイント | 制限 | ウィンドウ | スコープ |
|---|---|---|---|
| 物件一覧/取得 | 120 req | 1 分 | パートナーキーごと |
| テナント作成/更新 | 30 req | 1 分 | パートナーキーごと |
| 作業指示書 | 60 req | 1 分 | パートナーキーごと |
| 一括データエクスポート | 5 req | 1 時間 | パートナーキーごと |
| Webhook登録 | 10 req | 1 分 | パートナーキーごと |
レートリミッター実装
class AppFolioRateLimiter {
private tokens: number;
private lastRefill: number;
private readonly maxTokens: number;
private readonly refillRate: number; // トークン/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;
}
// 次のトークンが利用可能になるまで待機。後続のリクエストでこの呼び出し元を
// 起こす必要はありません。
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); // エンドポイント契約に基づいて設定
リトライ戦略
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("最大リトライ回数を超過しました");
}
バッチ処理
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;
}
エラーハンドリング
| 問題 | 原因 | 修正 |
|---|---|---|
| 429 Too Many Requests | パートナーレート制限超過 | Retry-Afterヘッダーを使用してバックオフ |
| 一括エクスポートで403 | 1時間あたりのエクスポート上限に達した | エクスポートを15分間隔でキューイング |
| 物件一覧でタイムアウト | 大規模ポートフォリオ(500ユニット以上) | per_page=50でページネーション |
| テナント更新で409 Conflict | 同じテナントへの同時書き込み | 新しいETagでリトライ |
| メンテナンス中に503 | スケジュールされた夜間ウィンドウ(午前2-4時PT) | リクエストをスキップし、ウィンドウ後に再試行 |
出力
- キューに入れられた作業を放置しない、自己スケジューリング型エンドポイント固有のリミッター
Retry-Afterの証拠と編集済み障害データを含む、制限付きリトライ結果- 永続化されたバッチ判定:完了、後でリトライのために一時停止、またはオペレーター調整のために隔離
例
サンドボックスのテナント更新バッチでは、リミッターをドキュメント化されたテナント書き込み上限以下に設定し、冪等性キーを使用して1レコードずつ処理し、各確認結果の後にカーソルを保持します。429を誘発して呼び出し元が追加リクエストなしで待機して再開することを確認し、次にレスポンス喪失を誘発してレコードが盲目的に再実行されるのではなく隔離されることを確認します。レートヘッダーが設定された上限と矛盾する場合、リトライを使い果たした場合、またはメンテナンスが開始された場合は、バッチを一時停止してカーソルを所有者に渡します。
リソース
次のステップ
appfolio-performance-tuningを参照してください。