AppFolio Errores Comunes
Resumen
La API Stack de AppFolio impulsa integraciones de gestión de propiedades para verificación de inquilinos, órdenes de trabajo, gestión de arrendamientos y contabilidad. Cada cartera opera bajo su propio subdominio ({company}.appfolio.com), lo que significa que una sola integración puede necesitar manejar múltiples URL base. Los errores a menudo provienen de una configuración de autenticación incorrecta, URL base incorrecta por cartera y violaciones de lógica de negocio como registros de inquilinos duplicados o fechas de arrendamiento conflictivas. Las fallas en la búsqueda de inquilinos (404) son el problema más frecuente, generalmente causado por apuntar al subdominio de cartera incorrecto. Esta referencia cubre fallas a nivel HTTP, errores de validación específicos de la gestión de propiedades y patrones de recuperación para los problemas más comunes.
Prerrequisitos
- Un registro de incidente con datos depurados que contenga el identificador de la cartera, el endpoint, el código de estado, el ID de correlación de la solicitud y la ventana de tiempo; nunca copie cargas útiles de inquilinos o arrendamientos en un ticket compartido.
- Acceso al endpoint de cartera (sandbox o producción) correcto y un propietario de credenciales que pueda rotar o validar las credenciales sin exponerlas en registros o argumentos de comandos.
- Una política de reintento limitada, un mecanismo de idempotencia para escrituras y una ruta de escalación operativa conocida para estados inciertos de inquilinos, arrendamientos u órdenes de trabajo.
Instrucciones
- Clasifique la respuesta por autenticación, límite de tasa, validación o falla del servidor y conserve solo los campos de diagnóstico depurados.
- Verifique la URL base de la cartera antes de cambiar las credenciales o reintentar un
404; un ID de inquilino válido en otra cartera no es evidencia de ausencia. - Para fallas
409o escrituras parciales, consulte el registro canónico y use la clave de idempotencia de la operación o la revisión del operador antes de emitir otra escritura. - Respete
Retry-Afterpara429y deténgase después del presupuesto de reintento configurado; pause el lote en5xxo resultados de escritura desconocidos.
Referencia de Errores
| Código | Mensaje | Causa | Solución |
|---|---|---|---|
401 | No autorizado | Par client_id/secret inválido o rotado | Regenerar credenciales en el portal de socios de AppFolio Stack |
403 | Prohibido | Cuenta no aprobada como socio de Stack | Completar la solicitud de socio en appfolio.com/stack |
404 | Inquilino no encontrado | URL base de cartera incorrecta o inquilino eliminado | Verificar que la URL base sea {company}.appfolio.com/api/v1 |
409 | Conflicto de arrendamiento | Fechas de arrendamiento superpuestas para la misma unidad | Verificar arrendamientos existentes en la unidad antes de crear uno nuevo |
422 | Validación fallida | Faltan campos obligatorios en la orden de trabajo o inquilino | Incluir todos los campos obligatorios: unit_id, description, priority |
429 | Demasiadas solicitudes | Se excedió el límite de 120 solicitudes/minuto | Implementar retroceso exponencial comenzando con 1s de retraso |
500 | Error interno del servidor | Problema de la plataforma AppFolio | Reintentar después de 30s; verificar status.appfolio.com |
503 | Servicio no disponible | Ventana de mantenimiento (generalmente fines de semana) | Reintentar con retroceso; suscribirse al calendario de mantenimiento |
Manejador de Errores
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: "Límite de tasa excedido", category: "rate_limit" };
}
if (status === 404 || status === 409 || status === 422) {
return { code: status, message: body, category: "validation" };
}
return { code: status, message: body, category: "server" };
}
Guía de Depuración
Errores de Autenticación
AppFolio utiliza Autenticación Básica HTTP con client_id:client_secret. Verifique que las credenciales no estén codificadas en URL. Cada cartera tiene su propia URL base; confirme que está apuntando al subdominio {company}.appfolio.com correcto. Las credenciales rotan con los cambios de aprobación de socios.
Errores de Límite de Tasa
La API Stack impone 120 solicitudes/minuto por clave API. Realice búsquedas de inquilinos en lote en lugar de llamadas individuales. Use el valor del encabezado Retry-After cuando esté presente. Los endpoints masivos (ej. /properties?page=1&per_page=100) reducen significativamente el recuento de llamadas. Los límites de tasa son por clave, no por cartera, por lo que las integraciones con múltiples carteras comparten el mismo presupuesto.
Errores de Validación
La creación de órdenes de trabajo requiere unit_id, description y priority. La creación de inquilinos requiere first_name, last_name y email. La creación de arrendamientos falla con 409 si las fechas se superponen con un arrendamiento activo existente en la misma unidad; consulte los arrendamientos actuales primero. Las fechas de mudanza de entrada y salida deben tener un formato ISO 8601 válido. Los IDs de unidad son específicos de la cartera y no se pueden reutilizar entre subdominios.
Manejo de Errores
| Escenario | Patrón | Recuperación |
|---|---|---|
| Búsqueda de inquilino devuelve 404 | Buscar por correo electrónico antes de crear | Usar endpoint /tenants?email= |
| Orden de trabajo 422 | Falta campo de prioridad | Establecer por defecto a normal si no se especifica |
| Conflicto de fecha de arrendamiento | Arrendamiento activo superpuesto | Terminar arrendamiento existente antes de crear nuevo |
| Falla parcial en importación masiva | Algunos registros rechazados | Analizar matriz de errores, reintentar solo registros fallidos |
| Token de autenticación expiró a medio lote | 401 en llamadas subsiguientes | Reautenticar y reanudar desde el último desplazamiento |
Diagnóstico Rápido
# Verificar conectividad de API sin colocar credenciales Basic Auth en 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"
Salida
- Una clasificación depurada de la falla y el contexto verificado de la cartera
- Una decisión de recuperación acotada: corregir configuración, retrasar/reintentar, reconciliar, rotar a través del propietario de credenciales o escalar un resultado de escritura desconocido
- Un recibo de incidente que identifique el lote afectado sin retener datos de inquilinos, arrendamientos o credenciales
Ejemplos
Cuando una importación de órdenes de trabajo recibe 429, deje de despachar nuevos registros, conserve el cursor del lote y las claves de idempotencia, y espere la ventana de reintento proporcionada por el servidor antes de reanudar en el mismo registro. Para un conflicto de arrendamiento 409, consulte el arrendamiento actual de la unidad a través de la cartera correcta y enrute el resultado a un operador autorizado en lugar de finalizar o reemplazar un arrendamiento automáticamente. Si la lectura de seguimiento no está disponible o el resultado de una escritura anterior es desconocido, ponga en cuarentena ese registro y continúe solo con trabajos seguros no relacionados.
Recursos
Próximos Pasos
Consulte appfolio-debug-bundle.