Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

AppFolio API 속도 제한을 스로틀링과 백오프로 처리합니다.

tons-of-skills-marketplace란 무엇인가요?

이 스킬은 AppFolio Stack API의 파트너별 속도 제한을 안전하게 관리하기 위한 솔루션을 제공합니다. 대량의 세입자 가져오기, 임대료 동기화, 작업 지시서 배치 업데이트와 같은 고부하 작업에서 발생하는 속도 제한 문제를 해결하는 데 초점을 맞춥니다. 특히 월말 임대 갱신 및 결제 처리 시 동시에 요청이 급증하는 상황에서도 안정적으로 API를 사용할 수 있도록 설계되었습니다. 이 스킬은 엔드포인트별 한도 설정, 토큰 버킷 기반 속도 제한기 구현, Retry-After 헤더를 존중하는 재시도 전략, 영속성 커서와 멱등성 키를 사용한 배치 처리를 포함합니다. 또한 429, 403, 503 등 다양한 오류 상황에 대한 명확한 처리 방법을 제시하며, 큐에 쌓인 작업을 중단 없이 처리하고, 재시도 예산 소진 시 배치를 일시 중지하거나 격리하는 메커니즘을 제공합니다. Claude Code, Cursor, Codex 등 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를 준수하며, 일시적인 공급자 장애에 지터(jitter)를 추가하여 재시도 횟수를 제한하십시오.
  3. 멱등성 키와 함께 영속성 커서에서 쓰기를 처리하고, 응답이 손실되었다고 해서 세입자 생성을 다시 재생하지 마십시오.
  4. 재시도 예산이 소진되거나, 유지 보수 기간에 도달하거나, 알 수 없는 쓰기 결과가 발생한 배치는 일시 중지하고 에스컬레이션하십시오.

속도 제한 참조

엔드포인트제한기간범위
속성 목록/조회120 요청1분파트너 키당
세입자 생성/수정30 요청1분파트너 키당
작업 지시서60 요청1분파트너 키당
대량 데이터 내보내기5 요청1시간파트너 키당
웹훅 등록10 요청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 대량 내보내기시간당 내보내기 한도 도달15분 간격으로 내보내기 큐잉
속성 목록 시간 초과대규모 포트폴리오 (500개 이상 유닛)per_page=50으로 페이지네이션
409 세입자 업데이트 충돌동일 세입자에 대한 동시 쓰기새 ETag로 재시도
503 유지 보수 중예정된 야간 유지보수 기간 (오전 2-4시 PT)요청 건너뛰고, 기간 후 재시도

출력

  • 큐에 쌓인 작업을 중단 없이 처리하는 자체 예약형 엔드포인트별 제한기
  • Retry-After 증거와 편집된 오류 데이터가 포함된 제한된 재시도 결과
  • 완료, 나중 재시도를 위해 일시 중지, 또는 운영자 조정을 위해 격리된 영속성 배치 결정

예제

샌드박스 세입자 업데이트 배치의 경우, 문서화된 세입자 쓰기 상한보다 낮게 제한기를 설정하고, 멱등성 키를 사용하여 한 번에 하나의 레코드를 처리하며, 각 확인된 결과 후 커서를 보존하십시오. 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".

관련 스킬