Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/appfolio-rate-limits/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill appfolio-rate-limits. Copyright stays with the author (MIT).

AppFolio Rate Limits

Overview

AppFolio's Stack API enforces per-partner rate limits to protect shared property management infrastructure. High-volume operations like bulk tenant imports, rent-roll syncs, and work-order batch updates can quickly exhaust quotas. Property managers running nightly portfolio syncs across hundreds of units must throttle carefully, especially during month-end when lease renewals and payment processing spike concurrently.

Prerequisites

• A verified per-endpoint limit from the current AppFolio partner contract or response headers; do not rely on a generic rate value for tenant writes.
• Persisted batch cursors, idempotency keys for every write, and an operator policy for pausing month-end or other safety-sensitive workloads.
• A staging fixture and request-budget owner who can prove retries, 429 behavior, and unknown-write handling without touching production tenants.

Instructions

1. Select the limiter ceiling for the specific endpoint and keep concurrency below the smallest applicable portfolio or partner limit.
2. Acquire a token before each request, honor Retry-After, and cap retries with jitter for transient provider failures.
3. Process writes from a persisted cursor with idempotency keys; never replay a tenant create just because the response was lost.
4. Pause and escalate batches that exhaust the retry budget, hit a maintenance window, or have an unknown write outcome.

Rate Limit Reference

Rate Limiter Implementation

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

Retry Strategy

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");
}

Batch Processing

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;
}

Error Handling

Output

• A self-scheduling, endpoint-specific limiter that cannot strand queued work
• Bounded retry outcomes with Retry-After evidence and redacted failure data
• A persisted batch decision: completed, paused for later retry, or quarantined for operator reconciliation

Examples

For a sandbox tenant-update batch, set the limiter below the documented tenant write ceiling, process one record at a time with idempotency keys, and preserve the cursor after each confirmed result. Induce a 429 to prove that callers wait and resume without an additional request, then induce a lost response to prove the record is quarantined rather than blindly replayed. If rate headers conflict with the configured ceiling, retries exhaust, or maintenance starts, pause the batch and hand the cursor to the owner.

Resources

• AppFolio Stack API

Next Steps

See appfolio-performance-tuning.