AppFolio 常見錯誤
概述
AppFolio 的 Stack API 為物業管理整合提供動力,支援租戶審查、工單、租約管理及會計功能。每個物業組合都在其各自的子網域({company}.appfolio.com)下運作,這意味著單一整合可能需要處理多個基礎 URL。錯誤通常源於驗證配置錯誤、每個物業組合的基礎 URL 不正確,以及業務邏輯違規(例如重複的租戶記錄或衝突的租約日期)。最常見的問題是租戶查詢失敗(404),通常是由於定位到錯誤的物業組合子網域所致。本參考資料涵蓋 HTTP 層級錯誤、物業管理特定的驗證錯誤,以及針對最常遇到問題的復原模式。
先決條件
- 一份編輯過的 incident 記錄,包含物業組合識別碼、端點、狀態碼、請求關聯 ID 及時間範圍;請勿將租戶或租約的 payload 複製到共享的 ticket 中。
- 能夠存取正確的沙箱或生產環境物業組合端點,以及一位憑證擁有者,其可以輪換或驗證憑證,但不得將憑證暴露在日誌或命令參數中。
- 一個有限制的重試策略、一個用於寫入操作的冪等性機制,以及一個已知的運維人員升級路徑,用於處理不確定的租戶、租約或工單狀態。
使用說明
- 根據驗證、速率限制、驗證或伺服器錯誤對回應進行分類,並僅保留經過編輯的診斷欄位。
- 在更改憑證或重試
404錯誤之前,先驗證物業組合的基礎 URL;在其他物業組合中存在有效的租戶 ID 並不能證明該租戶不存在。 - 對於
409或部分寫入失敗的情況,請查詢標準記錄,並使用操作的冪等性金鑰或經由運維人員審查後再發出另一次寫入。 - 對於
429錯誤,請遵守Retry-After標頭,並在達到設定的重試預算後停止;對於5xx或未知的寫入結果,請暫停批次處理。
錯誤參考
| 代碼 | 訊息 | 原因 | 修復 |
|---|---|---|---|
401 | Unauthorized | client_id/secret 配對無效或已輪換 | 在 AppFolio Stack 合作夥伴入口網站重新產生憑證 |
403 | Forbidden | 帳戶未核准為 Stack 合作夥伴 | 在 appfolio.com/stack 完成合作夥伴申請 |
404 | Tenant not found | 物業組合基礎 URL 錯誤或租戶已刪除 | 確認基礎 URL 為 {company}.appfolio.com/api/v1 |
409 | Lease conflict | 同一單位的租約日期重疊 | 在建立新租約前,先檢查現有的租約 |
422 | Validation failed | 工單或租戶缺少必要欄位 | 包含所有必要欄位:unit_id、description、priority |
429 | Too Many Requests | 超過每分鐘 120 次請求的限制 | 實作指數退避,初始延遲 1 秒 |
500 | Internal Server Error | AppFolio 平台問題 | 等待 30 秒後重試;檢查 status.appfolio.com |
503 | Service 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。