Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

AppFolio APIのレート制限をスロットリングとバックオフで処理します。

tons-of-skills-marketplace とは?

このスキルはAppFolio Stack APIのレート制限を管理するためのトークンバケットベースのレートリミッターと指数バックオフリトライ戦略を実装します。プロパティ管理のワークロード(テナント一括インポート、家賃収入同期、作業指示書のバッチ更新など)で高頻度のAPI呼び出しが必要な場合、パートナーキーごとのエンドポイント別制限を超えないよう制御します。主な機能には、エンドポイントごとに設定可能なトークンリフィルレート、429応答時のRetry-Afterヘッダー対応、べき乗バックオフとジッター付きリトライ、IDempotencyキーを用いた安全なバッチ処理、カーソルベースの再開可能性が含まれます。TypeScriptでの実装例が提供され、Claude CodeなどのAIエージェントがAppFolio APIとやり取りする際の堅牢なエラーハンドリングを実現します。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-rate-limits

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

AppFolio レート制限

概要

AppFolioのStack APIは、共有プロパティ管理インフラストラクチャを保護するためにパートナーごとのレート制限を適用しています。テナントの一括インポート、家賃収入の同期、作業指示書のバッチ更新といった大量処理は、クォータを急速に消費する可能性があります。数百戸のポートフォリオで夜間に同期を実行するプロパティマネージャーは、特に月末にリース更新と支払い処理が同時に増加する時期に、慎重なスロットリングが必要です。

前提条件

  • 現在のAppFolioパートナー契約またはレスポンスヘッダーからの、エンドポイントごとの検証済み制限値。テナント書き込みには汎用的なレート値を使用しないでください。
  • 永続化されたバッチカーソル、すべての書き込みに対する冪等性キー、および月末などの安全重視ワークロードを一時停止するためのオペレーターポリシー。
  • リトライ、429動作、および不明な書き込み処理を本番テナントに影響を与えずに検証できるステージングフィクスチャとリクエストバジェット責任者。

手順

  1. 特定のエンドポイントのリミッター上限を選択し、同時実行数を該当する最小のポートフォリオまたはパートナー制限以下に保ちます。
  2. 各リクエストの前にトークンを取得し、Retry-Afterを尊重し、一時的なプロバイダー障害に対してはジッター付きでリトライを制限します。
  3. 永続化されたカーソルから冪等性キーを使用して書き込みを処理します。レスポンスが失われたからといってテナント作成を再実行しないでください。
  4. リトライバジェットを使い果たした場合、メンテナンスウィンドウに達した場合、または書き込み結果が不明な場合は、バッチを一時停止してエスカレーションします。

レート制限リファレンス

エンドポイント制限ウィンドウスコープ
物件一覧/取得120 req1 分パートナーキーごと
テナント作成/更新30 req1 分パートナーキーごと
作業指示書60 req1 分パートナーキーごと
一括データエクスポート5 req1 時間パートナーキーごと
Webhook登録10 req1 分パートナーキーごと

レートリミッター実装

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ヘッダーを使用してバックオフ
一括エクスポートで4031時間あたりのエクスポート上限に達したエクスポートを15分間隔でキューイング
物件一覧でタイムアウト大規模ポートフォリオ(500ユニット以上)per_page=50でページネーション
テナント更新で409 Conflict同じテナントへの同時書き込み新しいETagでリトライ
メンテナンス中に503スケジュールされた夜間ウィンドウ(午前2-4時PT)リクエストをスキップし、ウィンドウ後に再試行

出力

  • キューに入れられた作業を放置しない、自己スケジューリング型エンドポイント固有のリミッター
  • Retry-Afterの証拠と編集済み障害データを含む、制限付きリトライ結果
  • 永続化されたバッチ判定:完了、後でリトライのために一時停止、またはオペレーター調整のために隔離

例

サンドボックスのテナント更新バッチでは、リミッターをドキュメント化されたテナント書き込み上限以下に設定し、冪等性キーを使用して1レコードずつ処理し、各確認結果の後にカーソルを保持します。429を誘発して呼び出し元が追加リクエストなしで待機して再開することを確認し、次にレスポンス喪失を誘発してレコードが盲目的に再実行されるのではなく隔離されることを確認します。レートヘッダーが設定された上限と矛盾する場合、リトライを使い果たした場合、またはメンテナンスが開始された場合は、バッチを一時停止してカーソルを所有者に渡します。

リソース

次のステップ

appfolio-performance-tuningを参照してください。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

jeremylongshore/tons-of-skills-marketplace

Apply production-ready patterns for AppFolio REST API integration. Trigger: "appfolio patterns".

関連スキル