Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

Diagnostiziere und behebe häufige Fehler bei der AppFolio-API-Integration.

Was ist tons-of-skills-marketplace?

Dieses Skill bietet eine umfassende Anleitung zur Diagnose und Behebung häufiger Fehler bei der Integration mit der AppFolio Stack API. Es behandelt HTTP-Fehler wie 401 (Unauthorized), 404 (Tenant not found), 409 (Lease conflict) und 429 (Too Many Requests) sowie geschäftsspezifische Validierungsfehler für Mietverträge, Arbeitsaufträge und Mieterdatensätze. Der Skill unterstützt Entwickler und Plattformen wie Claude Code, Cursor und Codex. Er enthält eine detaillierte Fehlerreferenz, eine TypeScript-Fehlerklassifikationsfunktion, ein Debugging-Handbuch mit Authentifizierungs-, Ratenbegrenzungs- und Validierungsstrategien sowie eine Quick-Diagnostic-CLI unter Verwendung von `netrc` zur sicheren Authentifizierung. Der Fokus liegt auf der korrekten Portfolio-Basis-URL und idempotenten Wiederholungsmechanismen, um Datenintegrität zu gewährleisten und Fehler in Multi-Portfolio-Umgebungen zu reduzieren.

Funktioniert mit✓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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. Klassifizieren Sie die Antwort nach Authentifizierungs-, Ratenbegrenzungs-, Validierungs- oder Serverfehlern und behalten Sie nur die redigierten Diagnosefelder.
  2. Überprüfen Sie die Portfolio-Basis-URL, bevor Sie Berechtigungen ändern oder einen 404 erneut versuchen; eine gültige Mieter-ID in einem anderen Portfolio ist kein Nachweis für Abwesenheit.
  3. Bei 409 oder 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.
  4. Beachten Sie Retry-After bei 429 und stoppen Sie nach dem konfigurierten Wiederholungsbudget; pausieren Sie den Batch bei 5xx oder unbekannten Schreibausgängen.

Fehlerreferenz

CodeNachrichtUrsacheLösung
401UnauthorizedUngültiges oder rotiertes client_id/secret-PaarBerechtigungen im AppFolio Stack Partnerportal neu generieren
403ForbiddenKonto nicht als Stack-Partner genehmigtPartnerantrag unter appfolio.com/stack abschließen
404Tenant not foundFalsche Portfolio-Basis-URL oder gelöschter MieterÜberprüfen, ob die Basis-URL {company}.appfolio.com/api/v1 ist
409Lease conflictÜberlappende Mietdaten für dieselbe EinheitVor Erstellung eines neuen Mietvertrags bestehende Mietverträge für die Einheit prüfen
422Validation failedFehlende Pflichtfelder bei Arbeitsauftrag oder MieterAlle Pflichtfelder angeben: unit_id, description, priority
429Too Many RequestsLimit von 120 Anfragen/Minute überschrittenExponentiellen Backoff ab 1s Verzögerung implementieren
500Internal Server ErrorAppFolio-PlattformproblemNach 30s erneut versuchen; status.appfolio.com überprüfen
503Service UnavailableWartungsfenster (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

SzenarioMusterWiederherstellung
Mieterabfrage gibt 404 zurückVor Erstellung per E-Mail suchen/tenants?email=-Endpunkt verwenden
Arbeitsauftrag 422Fehlendes priority-FeldStandardmäßig normal verwenden, falls nicht angegeben
MietdatenkonfliktÜberlappender aktiver MietvertragBestehenden Mietvertrag vor Neuerstellung beenden
Teilweiser Bulk-Import-FehlerEinige Datensätze abgelehntFehler-Array parsen, nur fehlgeschlagene Datensätze erneut versuchen
Auth-Token während Batch abgelaufen401 bei nachfolgenden AufrufenErneut 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.

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".

Verwandte Skills