Communitygithub.com

AppFolio 일반 오류

AppFolio API 통합 시 발생하는 일반적인 오류를 진단하고 수정합니다.

AppFolio 일반 오류란 무엇인가요?

이 스킬은 AppFolio Stack API를 통합하는 개발자 또는 AI 에이전트가 자주 마주치는 HTTP 오류와 비즈니스 로직 충돌을 진단하고 해결하는 방법을 제공합니다. 인증 설정 오류, 잘못된 포트폴리오 기본 URL, 중복 세입자 기록, 임대 날짜 충돌 등 주요 오류 원인을 분류하고, 각 상황에 맞는 복구 패턴을 제시합니다. Claude Code, Cursor와 같은 AI 코딩 에이전트에서 실행 가능하며, 오류 분류 함수와 디버깅 명령어를 포함하여 실무에서 바로 사용할 수 있습니다. 401, 404, 409, 429 등 주요 HTTP 상태 코드별 원인과 해결책을 표로 정리하고, 안전한 자격 증명 처리 및 재시도 정책을 강조합니다.

지원 대상✓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 Requests120회/분 한도 초과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)는 호출 수를 크게 줄입니다. 속도 제한은 포트폴리오가 아닌 키별로 적용되므로, 여러 포트폴리오 통합은 동일한 예산을 공유합니다.

유효성 검사 오류

작업 지시 생성에는 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".

관련 스킬