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
- 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.
- 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. - Pour les
409ou 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. - Respectez
Retry-Afterpour les429et arrêtez-vous après le budget de tentatives configuré ; mettez en pause le lot sur les5xxou les résultats d'écriture inconnus.
Référence des Erreurs
| Code | Message | Cause | Correctif |
|---|---|---|---|
401 | Non autorisé | Paire client_id/secret invalide ou modifiée | Régénérez les informations d'identification dans le portail partenaire AppFolio Stack |
403 | Interdit | Compte non approuvé en tant que partenaire Stack | Complétez la demande de partenariat sur appfolio.com/stack |
404 | Locataire non trouvé | Mauvaise URL de base du portefeuille ou locataire supprimé | Vérifiez que l'URL de base est {entreprise}.appfolio.com/api/v1 |
409 | Conflit de bail | Dates 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 validation | Champs obligatoires manquants sur l'ordre de travail ou le locataire | Incluez tous les champs obligatoires : unit_id, description, priority |
429 | Trop de demandes | Limite de 120 demandes/minute dépassée | Implémentez un backoff exponentiel commençant par un délai de 1 s |
500 | Erreur interne du serveur | Problème de plateforme AppFolio | Réessayez après 30 s ; consultez status.appfolio.com |
503 | Service indisponible | Fenê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énario | Modèle | Récupération |
|---|---|---|
| La recherche de locataire renvoie 404 | Recherchez par email avant de créer | Utilisez le point d'accès /tenants?email= |
| Ordre de travail 422 | Champ priorité manquant | Définissez par défaut sur normal si non spécifié |
| Conflit de date de bail | Bail actif qui se chevauche | Terminez le bail existant avant d'en créer un nouveau |
| Échec partiel d'importation en masse | Certains enregistrements rejetés | Analysez le tableau d'erreurs, réessayez uniquement les enregistrements échoués |
| Jeton d'authentification expiré en cours de lot | 401 sur les appels suivants | Ré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.