Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

診斷並修復常見的 AppFolio API 整合錯誤。

tons-of-skills-marketplace 是什麼?

此技能專為開發人員與 AI 代理設計,用於診斷及修復 AppFolio Stack API 整合時常見的錯誤。AppFolio 的 Stack API 支援物業管理整合,如租戶審查、工單、租約管理及會計功能,其中每個物業組合都使用各自獨立的子網域(`{company}.appfolio.com`)。常見錯誤包括驗證失敗、URL 配置錯誤、重複租戶記錄或租約日期衝突等。本技能會根據錯誤代碼(例如 401、403、404、409、422、429、503)分類錯誤類型(驗證、速率限制、伺服器錯誤),並提供具體的修復步驟。此外,還包含一個 TypeScript 錯誤處理器、用於診斷的 Bash 指令碼,以及針對批次操作、衝突處理與重試策略的最佳實務建議。主要支援平台包括 Claude Code 等 AI 代理工具,有助於開發者迅速定位問題、減少停機時間,並降低人為操作失誤。

相容平台✓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-common-errors

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

AppFolio 常見錯誤

概述

AppFolio 的 Stack API 為物業管理整合提供動力,支援租戶審查、工單、租約管理及會計功能。每個物業組合都在其各自的子網域({company}.appfolio.com)下運作,這意味著單一整合可能需要處理多個基礎 URL。錯誤通常源於驗證配置錯誤、每個物業組合的基礎 URL 不正確,以及業務邏輯違規(例如重複的租戶記錄或衝突的租約日期)。最常見的問題是租戶查詢失敗(404),通常是由於定位到錯誤的物業組合子網域所致。本參考資料涵蓋 HTTP 層級錯誤、物業管理特定的驗證錯誤,以及針對最常遇到問題的復原模式。

先決條件

  • 一份編輯過的 incident 記錄,包含物業組合識別碼、端點、狀態碼、請求關聯 ID 及時間範圍;請勿將租戶或租約的 payload 複製到共享的 ticket 中。
  • 能夠存取正確的沙箱或生產環境物業組合端點,以及一位憑證擁有者,其可以輪換或驗證憑證,但不得將憑證暴露在日誌或命令參數中。
  • 一個有限制的重試策略、一個用於寫入操作的冪等性機制,以及一個已知的運維人員升級路徑,用於處理不確定的租戶、租約或工單狀態。

使用說明

  1. 根據驗證、速率限制、驗證或伺服器錯誤對回應進行分類,並僅保留經過編輯的診斷欄位。
  2. 在更改憑證或重試 404 錯誤之前,先驗證物業組合的基礎 URL;在其他物業組合中存在有效的租戶 ID 並不能證明該租戶不存在。
  3. 對於 409 或部分寫入失敗的情況,請查詢標準記錄,並使用操作的冪等性金鑰或經由運維人員審查後再發出另一次寫入。
  4. 對於 429 錯誤,請遵守 Retry-After 標頭,並在達到設定的重試預算後停止;對於 5xx 或未知的寫入結果,請暫停批次處理。

錯誤參考

代碼訊息原因修復
401Unauthorizedclient_id/secret 配對無效或已輪換在 AppFolio Stack 合作夥伴入口網站重新產生憑證
403Forbidden帳戶未核准為 Stack 合作夥伴在 appfolio.com/stack 完成合作夥伴申請
404Tenant not found物業組合基礎 URL 錯誤或租戶已刪除確認基礎 URL 為 {company}.appfolio.com/api/v1
409Lease conflict同一單位的租約日期重疊在建立新租約前,先檢查現有的租約
422Validation failed工單或租戶缺少必要欄位包含所有必要欄位:unit_id、description、priority
429Too Many Requests超過每分鐘 120 次請求的限制實作指數退避,初始延遲 1 秒
500Internal Server ErrorAppFolio 平台問題等待 30 秒後重試;檢查 status.appfolio.com
503Service Unavailable維護時段(通常在週末)使用退避機制重試;訂閱維護行事曆

錯誤處理器

interface AppFolioError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "validation" | "server";
}

function classifyAppFolioError(status: number, body: string): AppFolioError {
  if (status === 401 || status === 403) {
    return { code: status, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limit exceeded", category: "rate_limit" };
  }
  if (status === 404 || status === 409 || status === 422) {
    return { code: status, message: body, category: "validation" };
  }
  return { code: status, message: body, category: "server" };
}

除錯指南

驗證錯誤

AppFolio 使用 HTTP Basic Auth,搭配 client_id:client_secret。請確認憑證未經過 URL 編碼。每個物業組合都有其自己的基礎 URL — 請確認您正在定位到正確的 {company}.appfolio.com 子網域。憑證會在合作夥伴核准變更時輪換。

速率限制錯誤

Stack API 對每個 API 金鑰實施每分鐘 120 次請求的限制。請批次查詢租戶,而非個別呼叫。當存在 Retry-After 標頭時,請使用其值。批次端點(例如 /properties?page=1&per_page=100)可大幅減少呼叫次數。速率限制是針對金鑰,而非針對物業組合,因此多物業組合的整合會共享相同的預算。

驗證錯誤

建立工單需要 unit_id、description 及 priority。建立租戶需要 first_name、last_name 及 email。如果租約日期與同一單位上現有的有效租約重疊,建立租約會失敗並回傳 409 — 請先查詢目前的租約。入住與遷出日期必須是有效的 ISO 8601 格式。單位 ID 是物業組合特定的,無法在不同的子網域間重複使用。

錯誤處理

情境模式復原
租戶查詢回傳 404在建立前先透過電子郵件搜尋使用 /tenants?email= 端點
工單 422缺少 priority 欄位若未指定,預設為 normal
租約日期衝突現有的有效租約重疊在建立新租約前,先結束現有租約
批次匯入部分失敗部分記錄被拒絕解析錯誤陣列,僅重試失敗的記錄
驗證令牌在批次處理過程中過期後續呼叫出現 401重新驗證並從最後的偏移量繼續

快速診斷

# 驗證 API 連線,而不將 Basic Auth 憑證放在 argv 中。
NETRC_FILE="$(mktemp)"
trap 'rm -f "$NETRC_FILE"' EXIT
chmod 600 "$NETRC_FILE"
APPFOLIO_HOST="${APPFOLIO_BASE_URL#https://}"
printf 'machine %s login %s password %s\n' "$APPFOLIO_HOST" \
  "$APPFOLIO_CLIENT_ID" "$APPFOLIO_CLIENT_SECRET" > "$NETRC_FILE"
curl -s -o /dev/null -w "%{http_code}" --netrc-file "$NETRC_FILE" \
  "${APPFOLIO_BASE_URL}/api/v1/properties"

輸出

  • 失敗的編輯後分類以及已驗證的物業組合上下文
  • 一個有限制的復原決策:修正配置、延遲/重試、協調、透過憑證擁有者輪換憑證,或升級未知的寫入結果
  • 一份 incident 收據,用於識別受影響的批次,而不保留租戶、租約或憑證資料

範例

當工單匯入收到 429 時,停止分派新記錄,保留批次游標與冪等性金鑰,並等待伺服器提供的重試視窗,然後從同一記錄繼續。對於 409 租約衝突,透過正確的物業組合查詢該單位的當前租約,並將結果轉發給授權的運維人員,而不是自動結束或取代租約。如果後續的讀取無法進行,或先前寫入的結果未知,請將該記錄隔離,並僅繼續處理無關的安全工作。

資源

下一步

請參閱 appfolio-debug-bundle。

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

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

Handle AppFolio API rate limits with throttling and backoff. Trigger: "appfolio rate limit".

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".

相關技能