AppFolio 常见错误
概述
AppFolio 的 Stack API 为物业管理集成提供支持,涵盖租户筛选、工单、租赁管理和会计。每个投资组合都在自己的子域名下运行({company}.appfolio.com),这意味着单个集成可能需要处理多个基础 URL。错误通常源于认证配置错误、每个投资组合的基础 URL 不正确,以及业务逻辑违规,例如重复的租户记录或冲突的租赁日期。租户查找失败(404)是最常见的问题,通常是由于定位到了错误的投资组合子域名。本参考涵盖了 HTTP 级别的故障、特定于物业管理的验证错误,以及针对最常遇到的问题的恢复模式。
前提条件
- 一份经过脱敏处理的事件记录,包含投资组合标识符、端点、状态码、请求关联 ID 和时间窗口;切勿将租户或租赁负载复制到共享工单中。
- 能够访问正确的沙箱或生产投资组合端点,以及一位凭证所有者,他可以在不将凭据暴露在日志或命令参数中的情况下轮换或验证凭据。
- 一个有界的重试策略、一个用于写入操作的幂等性机制,以及一个已知的操作员升级路径,用于处理不确定的租户、租赁或工单状态。
说明
- 根据认证、速率限制、验证或服务器故障对响应进行分类,并仅保留经过脱敏处理的诊断字段。
- 在更改凭据或重试
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 使用带有 client_id:client_secret 的 HTTP 基本认证。请确认凭据未进行 URL 编码。每个投资组合都有其自己的基础 URL — 请确认您正在访问正确的 {company}.appfolio.com 子域名。凭据会在合作伙伴批准状态变更时轮换。
速率限制错误
Stack API 对每个 API 密钥强制执行每分钟 120 次请求的限制。请批量查找租户,而不是单独调用。当存在 Retry-After 头部时,请使用其值。批量端点(例如 /properties?page=1&per_page=100)可以显著减少 API 调用次数。速率限制是按密钥而不是按投资组合实施的,因此多投资组合集成共享相同的配额。
验证错误
创建工单需要 unit_id、description 和 priority。创建租户需要 first_name、last_name 和 email。如果租赁日期与同一单元上的现有有效租赁重叠,创建租赁将失败并返回 409 错误 — 请先查询当前租赁。入住和搬出日期必须是有效的 ISO 8601 格式。单元 ID 是特定于投资组合的,不能跨子域名重用。
错误处理
| 场景 | 模式 | 恢复方法 |
|---|---|---|
| 租户查找返回 404 | 在创建前先通过电子邮件搜索 | 使用 /tenants?email= 端点 |
| 工单 422 | 缺少 priority 字段 | 如果未指定,则默认为 normal |
| 租赁日期冲突 | 有效的租赁时间重叠 | 在创建新租赁前结束现有租赁 |
| 批量导入部分失败 | 部分记录被拒绝 | 解析错误数组,仅重试失败的记录 |
| 批量处理中认证令牌过期 | 后续调用返回 401 | 重新认证并从上次偏移量恢复 |
快速诊断
# 验证 API 连接,同时避免将基本认证凭据放在 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"
输出
- 经过脱敏处理的失败分类和经过验证的投资组合上下文
- 一个有界的恢复决策:更正配置、延迟/重试、协调、通过凭证所有者轮换凭据,或升级处理未知的写入结果
- 一份事件记录,标识受影响的批次,但不保留租户、租赁或凭据数据
示例
当工单导入收到 429 错误时,停止分发新记录,保留批次游标和幂等性密钥,并在服务器提供的重试窗口结束后,从同一记录处恢复。对于 409 租赁冲突,通过正确的投资组合查询该单元当前的有效租赁,并将结果路由给授权操作员,而不是自动结束或替换租赁。如果后续的读取操作不可用或先前写入的结果未知,请隔离该记录,并仅继续执行不相关的安全操作。
资源
后续步骤
参见 appfolio-debug-bundle。