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 | 1分あたり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 ベーシック認証を 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= エンドポイントを使用 |
| 作業指示で 422 | priority フィールドが欠落 | 未指定の場合は 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 を参照してください。