Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

诊断并修复常见的 AppFolio API 集成错误。

tons-of-skills-marketplace 是什么?

该技能专门用于诊断和修复 AppFolio Stack API 集成中遇到的常见错误。AppFolio Stack API 支持物业管理集成,但每个投资组合(portfolio)都运行在自己的子域名下,导致单一集成可能需要处理多个基础 URL,从而容易引发认证配置错误、基础 URL 不匹配以及业务逻辑冲突(如重复租户记录或租赁日期冲突)等问题。技能覆盖了 HTTP 级别错误(如 401、403、404、409、422、429、500、503)、特定于物业管理的验证错误以及恢复模式,并提供了一个 TypeScript 错误分类函数。它支持在 Claude Code、Cursor、Codex 等 AI 代理平台上使用,通过明确的指令和诊断指南帮助开发者快速定位问题(如检查认证凭据、验证基础 URL、处理限速重试),并以安全的方式输出失败分类、恢复决策和事件记录,而不暴露敏感数据。

兼容平台✓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 级别的故障、特定于物业管理的验证错误,以及针对最常遇到的问题的恢复模式。

前提条件

  • 一份经过脱敏处理的事件记录,包含投资组合标识符、端点、状态码、请求关联 ID 和时间窗口;切勿将租户或租赁负载复制到共享工单中。
  • 能够访问正确的沙箱或生产投资组合端点,以及一位凭证所有者,他可以在不将凭据暴露在日志或命令参数中的情况下轮换或验证凭据。
  • 一个有界的重试策略、一个用于写入操作的幂等性机制,以及一个已知的操作员升级路径,用于处理不确定的租户、租赁或工单状态。

说明

  1. 根据认证、速率限制、验证或服务器故障对响应进行分类,并仅保留经过脱敏处理的诊断字段。
  2. 在更改凭据或重试 404 错误之前,先验证投资组合的基础 URL;在其他投资组合中的有效租户 ID 并不能证明该租户不存在。
  3. 对于 409 错误或部分写入失败,查询规范记录,并使用操作的幂等性密钥或操作员审查,然后再发起另一次写入。
  4. 对于 429 错误,遵守 Retry-After 头部的指示,并在达到配置的重试预算后停止;对于 5xx 错误或未知的写入结果,暂停批处理操作。

错误参考

状态码消息原因修复方法
401Unauthorized无效或已轮换的 client_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 使用带有 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。

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

相关技能