AppFolio Häufige Fehler
Überblick
Die AppFolio Stack API ermöglicht Integrationen in Property-Management-Systeme für Mieter-Screening, Arbeitsaufträge, Mietverwaltung und Buchhaltung. Jedes Portfolio hat seine eigene Subdomain ({company}.appfolio.com), sodass eine einzelne Integration mehrere Basis-URLs verwalten muss. Fehler treten häufig aufgrund von Authentifizierungsfehlkonfigurationen, falschen Basis-URLs pro Portfolio oder Verstößen gegen die Geschäftslogik wie doppelten Mieterdatensätzen oder widersprüchlichen Mietdaten auf. Mieter-Suchfehler (404) sind das häufigste Problem, das meist durch die Verwendung der falschen Portfolio-Subdomain verursacht wird. Diese Referenz deckt HTTP-Fehler, property-management-spezifische Validierungsfehler und Wiederholungsstrategien für die häufigsten Probleme ab.
Voraussetzungen
- Ein redigierter Incident-Datensatz, der die Portfolio-ID, den Endpunkt, den Statuscode, die Anfrage-Korrelations-ID und das Zeitfenster enthält; kopieren Sie niemals Mieter- oder Mietvertragsdaten in ein freigegebenes Ticket.
- Zugriff auf den korrekten Sandbox- oder Produktions-Portfolio-Endpunkt und einen Berechtigungsinhaber, der Berechtigungen rotieren oder validieren kann, ohne sie in Protokollen oder Befehlsargumenten zu exponieren.
- Eine begrenzte Wiederholungsrichtlinie, einen Idempotenzmechanismus für Schreibvorgänge und einen bekannten Eskalationspfad für unsichere Mieter-, Mietvertrags- oder Arbeitsauftragszustände.
Anweisungen
- Klassifizieren Sie die Antwort nach Authentifizierungs-, Ratenbegrenzungs-, Validierungs- oder Serverfehlern und behalten Sie nur die redigierten Diagnosefelder.
- Überprüfen Sie die Portfolio-Basis-URL, bevor Sie Berechtigungen ändern oder einen
404erneut versuchen; eine gültige Mieter-ID in einem anderen Portfolio ist kein Nachweis für Abwesenheit. - Bei
409oder teilweisen Schreibfehlern fragen Sie den kanonischen Datensatz ab und verwenden Sie den Idempotenzschlüssel der Operation oder die Prüfung des Operators, bevor Sie einen weiteren Schreibvorgang durchführen. - Beachten Sie
Retry-Afterbei429und stoppen Sie nach dem konfigurierten Wiederholungsbudget; pausieren Sie den Batch bei5xxoder unbekannten Schreibausgängen.
Fehlerreferenz
| Code | Nachricht | Ursache | Lösung |
|---|---|---|---|
401 | Unauthorized | Ungültiges oder rotiertes client_id/secret-Paar | Berechtigungen im AppFolio Stack Partnerportal neu generieren |
403 | Forbidden | Konto nicht als Stack-Partner genehmigt | Partnerantrag unter appfolio.com/stack abschließen |
404 | Tenant not found | Falsche Portfolio-Basis-URL oder gelöschter Mieter | Überprüfen, ob die Basis-URL {company}.appfolio.com/api/v1 ist |
409 | Lease conflict | Überlappende Mietdaten für dieselbe Einheit | Vor Erstellung eines neuen Mietvertrags bestehende Mietverträge für die Einheit prüfen |
422 | Validation failed | Fehlende Pflichtfelder bei Arbeitsauftrag oder Mieter | Alle Pflichtfelder angeben: unit_id, description, priority |
429 | Too Many Requests | Limit von 120 Anfragen/Minute überschritten | Exponentiellen Backoff ab 1s Verzögerung implementieren |
500 | Internal Server Error | AppFolio-Plattformproblem | Nach 30s erneut versuchen; status.appfolio.com überprüfen |
503 | Service Unavailable | Wartungsfenster (normalerweise am Wochenende) | Mit Backoff erneut versuchen; Wartungskalender abonnieren |
Fehlerbehandlung
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" };
}
Debugging-Anleitung
Authentifizierungsfehler
AppFolio verwendet HTTP Basic Auth mit client_id:client_secret. Stellen Sie sicher, dass die Berechtigungen nicht URL-kodiert sind. Jedes Portfolio hat seine eigene Basis-URL – bestätigen Sie, dass Sie die richtige {company}.appfolio.com-Subdomain verwenden. Berechtigungen rotieren bei Partner-Genehmigungsänderungen.
Ratenbegrenzungsfehler
Die Stack API erzwingt 120 Anfragen/Minute pro API-Schlüssel. Batch-Mieterabfragen anstelle einzelner Aufrufe durchführen. Verwenden Sie den Retry-After-Header, wenn vorhanden. Bulk-Endpunkte (z.B. /properties?page=1&per_page=100) reduzieren die Anzahl der Aufrufe erheblich. Ratenbegrenzungen gelten pro Schlüssel, nicht pro Portfolio, sodass Multi-Portfolio-Integrationen dasselbe Budget teilen.
Validierungsfehler
Die Erstellung von Arbeitsaufträgen erfordert unit_id, description und priority. Die Mietererstellung erfordert first_name, last_name und email. Die Mietvertragserstellung schlägt mit 409 fehl, wenn die Daten mit einem bestehenden aktiven Mietvertrag für dieselbe Einheit überlappen – fragen Sie zuerst die aktuellen Mietverträge ab. Einzugs- und Auszugsdaten müssen das gültige ISO-8601-Format haben. Einheits-IDs sind portfoliospezifisch und können nicht über Subdomains hinweg wiederverwendet werden.
Fehlerbehandlung
| Szenario | Muster | Wiederherstellung |
|---|---|---|
| Mieterabfrage gibt 404 zurück | Vor Erstellung per E-Mail suchen | /tenants?email=-Endpunkt verwenden |
| Arbeitsauftrag 422 | Fehlendes priority-Feld | Standardmäßig normal verwenden, falls nicht angegeben |
| Mietdatenkonflikt | Überlappender aktiver Mietvertrag | Bestehenden Mietvertrag vor Neuerstellung beenden |
| Teilweiser Bulk-Import-Fehler | Einige Datensätze abgelehnt | Fehler-Array parsen, nur fehlgeschlagene Datensätze erneut versuchen |
| Auth-Token während Batch abgelaufen | 401 bei nachfolgenden Aufrufen | Erneut authentifizieren und ab letztem Offset fortsetzen |
Schnelldiagnose
# API-Konnektivität überprüfen, ohne Basic Auth-Anmeldedaten in argv zu platzieren.
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"
Ausgabe
- Eine redigierte Klassifizierung des Fehlers und der verifizierte Portfolio-Kontext
- Eine begrenzte Wiederherstellungsentscheidung: korrekte Konfiguration, Verzögerung/Wiederholung, Abgleich, Rotieren der Berechtigungen durch den Berechtigungsinhaber oder Eskalation eines unbekannten Schreibergebnisses
- Ein Incident-Beleg, der den betroffenen Batch identifiziert, ohne Mieter-, Mietvertrags- oder Berechtigungsdaten zu speichern
Beispiele
Wenn ein Arbeitsauftragsimport einen 429 erhält, stoppen Sie die Verteilung neuer Datensätze, behalten Sie den Batch-Cursor und die Idempotenzschlüssel und warten Sie auf das vom Server bereitgestellte Wiederholungsfenster, bevor Sie beim selben Datensatz fortfahren. Bei einem 409-Mietkonflikt fragen Sie den aktuellen Mietvertrag der Einheit über das korrekte Portfolio ab und leiten das Ergebnis an einen autorisierten Operator weiter, anstatt einen Vertrag automatisch zu beenden oder zu ersetzen. Wenn der Folge-Lesevorgang nicht verfügbar oder das Ergebnis eines vorherigen Schreibvorgangs unbekannt ist, isolieren Sie diesen Datensatz und fahren Sie nur mit nicht zusammenhängenden sicheren Arbeiten fort.
Ressourcen
Nächste Schritte
Siehe appfolio-debug-bundle.