jeremylongshore/tons-of-skills-marketplace

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

Endpoint	Limit	Window	Scope
Properties list/get	120 req	1 minute	Per partner key
Tenant create/update	30 req	1 minute	Per partner key
Work orders	60 req	1 minute	Per partner key
Bulk data export	5 req	1 hour	Per partner key
Webhooks registration	10 req	1 minute	Per partner key

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

Issue	Cause	Fix
429 Too Many Requests	Exceeded partner rate limit	Backoff using Retry-After header
403 on bulk export	Hourly export cap reached	Queue exports with 15-min spacing
Timeout on property list	Large portfolio (500+ units)	Paginate with per_page=50
409 Conflict on tenant update	Concurrent write to same tenant	Retry with fresh ETag
503 during maintenance	Scheduled nightly window (2-4 AM PT)	Skip requests, retry after window

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.