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)는 호출 수를 크게 줄입니다. 속도 제한은 포트폴리오가 아닌 키별로 적용되므로, 여러 포트폴리오 통합은 동일한 예산을 공유합니다.
유효성 검사 오류
작업 지시 생성에는 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 참조.