Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

Diagnostiquez et corrigez les erreurs courantes d'intégration de l'API AppFolio.

Qu'est-ce que tons-of-skills-marketplace ?

Cette compétence fournit un guide complet pour diagnostiquer et résoudre les erreurs les plus fréquentes lors de l'intégration avec l'API Stack d'AppFolio. Elle couvre les problèmes d'authentification, les limites de débit, les erreurs de validation et les défaillances serveur. La documentation inclut un tableau de référence des erreurs avec leurs causes et correctifs, un classificateur d'erreurs en TypeScript, et des instructions pratiques pour la récupération. Destinée aux développeurs et aux agents IA utilisant des plateformes comme Claude Code ou Cursor, cette compétence permet de traiter efficacement les incidents sans exposer de données sensibles.

Compatible avec✓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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Erreurs Courantes AppFolio

Présentation

L'API Stack d'AppFolio alimente les intégrations de gestion immobilière pour la vérification des locataires, les ordres de travail, la gestion des baux et la comptabilité. Chaque portefeuille fonctionne sous son propre sous-domaine ({entreprise}.appfolio.com), ce qui signifie qu'une seule intégration peut devoir gérer plusieurs URL de base. Les erreurs proviennent généralement d'une mauvaise configuration de l'authentification, d'URL de base incorrectes par portefeuille et de violations de la logique métier telles que des enregistrements de locataires en double ou des dates de bail contradictoires. Les échecs de recherche de locataire (404) sont le problème le plus fréquent, généralement causé par un ciblage du mauvais sous-domaine de portefeuille. Cette référence couvre les défaillances au niveau HTTP, les erreurs de validation spécifiques à la gestion immobilière et les modèles de récupération pour les problèmes les plus courants.

Prérequis

  • Un enregistrement d'incident expurgé contenant l'identifiant du portefeuille, le point d'accès, le code d'état, l'ID de corrélation de la demande et la fenêtre temporelle ; ne copiez jamais les charges utiles des locataires ou des baux dans un ticket partagé.
  • Accès au bon point d'accès du portefeuille sandbox ou de production et à un propriétaire d'informations d'identification qui peut les faire pivoter ou les valider sans les exposer dans les journaux ou les arguments de commande.
  • Une politique de tentatives limitée, un mécanisme d'idempotence pour les écritures, et une voie d'escalade connue pour l'opérateur en cas d'état incertain du locataire, du bail ou de l'ordre de travail.

Instructions

  1. Classez la réponse selon qu'il s'agit d'une erreur d'authentification, de limite de débit, de validation ou de défaillance serveur et ne conservez que les champs de diagnostic expurgés.
  2. Vérifiez l'URL de base du portefeuille avant de modifier les informations d'identification ou de réessayer une 404 ; un ID de locataire valide dans un autre portefeuille n'est pas une preuve d'absence.
  3. Pour les 409 ou les échecs d'écriture partielle, interrogez l'enregistrement canonique et utilisez la clé d'idempotence de l'opération ou l'examen de l'opérateur avant d'effectuer une autre écriture.
  4. Respectez Retry-After pour les 429 et arrêtez-vous après le budget de tentatives configuré ; mettez en pause le lot sur les 5xx ou les résultats d'écriture inconnus.

Référence des Erreurs

CodeMessageCauseCorrectif
401Non autoriséPaire client_id/secret invalide ou modifiéeRégénérez les informations d'identification dans le portail partenaire AppFolio Stack
403InterditCompte non approuvé en tant que partenaire StackComplétez la demande de partenariat sur appfolio.com/stack
404Locataire non trouvéMauvaise URL de base du portefeuille ou locataire suppriméVérifiez que l'URL de base est {entreprise}.appfolio.com/api/v1
409Conflit de bailDates de bail qui se chevauchent pour la même unitéVérifiez les baux existants sur l'unité avant d'en créer un nouveau
422Échec de validationChamps obligatoires manquants sur l'ordre de travail ou le locataireIncluez tous les champs obligatoires : unit_id, description, priority
429Trop de demandesLimite de 120 demandes/minute dépasséeImplémentez un backoff exponentiel commençant par un délai de 1 s
500Erreur interne du serveurProblème de plateforme AppFolioRéessayez après 30 s ; consultez status.appfolio.com
503Service indisponibleFenêtre de maintenance (généralement le week-end)Réessayez avec backoff ; abonnez-vous au calendrier de maintenance

Gestionnaire d'Erreurs

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" };
}

Guide de Débogage

Erreurs d'Authentification

AppFolio utilise l'authentification de base HTTP avec client_id:client_secret. Vérifiez que les informations d'identification ne sont pas encodées en URL. Chaque portefeuille a sa propre URL de base – confirmez que vous ciblez le bon sous-domaine {entreprise}.appfolio.com. Les informations d'identification changent en fonction des modifications de l'approbation du partenaire.

Erreurs de Limite de Débit

L'API Stack applique une limite de 120 demandes/minute par clé API. Effectuez des recherches de locataires par lots plutôt que des appels individuels. Utilisez la valeur de l'en-tête Retry-After lorsqu'elle est présente. Les points d'accès groupés (par exemple, /properties?page=1&per_page=100) réduisent considérablement le nombre d'appels. Les limites de débit sont par clé, pas par portefeuille, donc les intégrations multi-portefeuilles partagent le même budget.

Erreurs de Validation

La création d'un ordre de travail nécessite unit_id, description et priority. La création d'un locataire nécessite first_name, last_name et email. La création d'un bail échoue avec un 409 si les dates chevauchent un bail actif existant sur la même unité – interrogez d'abord les baux en cours. Les dates d'emménagement et de déménagement doivent être au format ISO 8601 valide. Les ID d'unité sont spécifiques au portefeuille et ne peuvent pas être réutilisés entre les sous-domaines.

Gestion des Erreurs

ScénarioModèleRécupération
La recherche de locataire renvoie 404Recherchez par email avant de créerUtilisez le point d'accès /tenants?email=
Ordre de travail 422Champ priorité manquantDéfinissez par défaut sur normal si non spécifié
Conflit de date de bailBail actif qui se chevaucheTerminez le bail existant avant d'en créer un nouveau
Échec partiel d'importation en masseCertains enregistrements rejetésAnalysez le tableau d'erreurs, réessayez uniquement les enregistrements échoués
Jeton d'authentification expiré en cours de lot401 sur les appels suivantsRéauthentifiez-vous et reprenez à partir du dernier décalage

Diagnostic Rapide

# Vérifiez la connectivité API sans placer les informations d'identification Basic Auth dans argv.
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"

Résultat

  • Une classification expurgée de la défaillance et le contexte vérifié du portefeuille
  • Une décision de récupération limitée : configuration correcte, délai/tentative, réconciliation, rotation via le propriétaire des informations d'identification, ou escalade d'un résultat d'écriture inconnu
  • Un reçu d'incident qui identifie le lot affecté sans conserver les données du locataire, du bail ou des informations d'identification

Exemples

Lorsqu'une importation d'ordres de travail reçoit un 429, arrêtez d'envoyer de nouveaux enregistrements, conservez le curseur du lot et les clés d'idempotence, et attendez la fenêtre de tentative fournie par le serveur avant de reprendre au même enregistrement. Pour un conflit de bail 409, interrogez le bail actuel de l'unité via le bon portefeuille et acheminez le résultat vers un opérateur autorisé plutôt que de mettre fin ou de remplacer un bail automatiquement. Si la lecture de suivi n'est pas disponible ou si le résultat d'une écriture antérieure est inconnu, mettez cet enregistrement en quarantaine et continuez uniquement avec les travaux sans danger non liés.

Ressources

Prochaines Étapes

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

Skills associés