Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

AppFolio API 統合エラーの診断と修正を行います。

tons-of-skills-marketplace とは?

このスキルは、AppFolio Stack API を使用した物件管理統合において頻発するエラーを診断し、修正するためのものです。主に対応するエラーは、認証設定ミス、ポートフォリオごとの誤ったベース URL、重複テナントやリース日付の競合などのビジネスロジック違反です。特に多いテナント検索の 404 エラーは、間違ったポートフォリオサブドメインを指定しているケースがほとんどです。このスキルは、HTTP ステータスコードに基づくエラー分類、ポートフォリオベース URL の検証、レート制限への対応、そしてべき等性を考慮したリカバリ手順を提供します。また、認証情報を安全に扱うためのシェルスクリプトや、エラーを分類する TypeScript コードも含まれています。プラットフォームとしては、Claude Code や Cursor などの AI エージェントでの使用を想定しており、ユーザーが「appfolio error」とトリガーすることで、エラーログやインシデントレコードに基づいた具体的な修正手順を提案します。

対応✓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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 Requests1分あたり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 ベーシック認証を client_id:client_secret で使用します。資格情報が URL エンコードされていないことを確認してください。各ポートフォリオには独自のベース URL があります。正しい {company}.appfolio.com サブドメインをターゲットにしていることを確認してください。資格情報は、パートナー承認の変更に応じてローテーションされます。

レート制限エラー

Stack API は API キーごとに 1 分あたり 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= エンドポイントを使用
作業指示で 422priority フィールドが欠落未指定の場合は normal をデフォルトとして使用
リース日付の競合アクティブなリースが重複新しいリースを作成する前に既存のリースを終了
一括インポートの部分的な失敗一部のレコードが拒否されたエラー配列を解析し、失敗したレコードのみを再試行
バッチ処理中に認証トークンが期限切れ後続の呼び出しで 401再認証し、最後のオフセットから再開

クイック診断

# Basic Auth 資格情報を argv に配置せずに API 接続を確認します。
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".

関連スキル