Communitygithub.com

jeremylongshore/tons-of-skills-marketplace

Diagnostica y soluciona errores comunes de integración con la API de AppFolio.

¿Qué es tons-of-skills-marketplace?

Esta skill está diseñada para desarrolladores que integran sistemas de gestión de propiedades con la API Stack de AppFolio. Proporciona un enfoque sistemático para diagnosticar y resolver errores HTTP comunes, como 401, 404, 409 y 429, que surgen por configuraciones incorrectas de autenticación, URL base incorrecta por cartera, o violaciones de lógica de negocio (ej. fechas de arrendamiento superpuestas). Incluye un clasificador de errores en TypeScript, una guía de depuración detallada por categoría (autenticación, límite de tasa, validación, servidor) y comandos curl seguros para verificar conectividad sin exponer credenciales. La skill recomienda políticas de reintento limitadas, mecanismos de idempotencia y una ruta clara de escalación para casos inciertos. Es compatible con cualquier agente que procese incidentes de API, como Claude Code, y su activación típica es "appfolio error". Útil para equipos de integración que manejan múltiples carteras AppFolio y necesitan reducir el tiempo de resolución de fallos.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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.
  2. 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.
  3. Para fallas 409 o 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.
  4. Respete Retry-After para 429 y deténgase después del presupuesto de reintento configurado; pause el lote en 5xx o resultados de escritura desconocidos.

Referencia de Errores

CódigoMensajeCausaSolución
401No autorizadoPar client_id/secret inválido o rotadoRegenerar credenciales en el portal de socios de AppFolio Stack
403ProhibidoCuenta no aprobada como socio de StackCompletar la solicitud de socio en appfolio.com/stack
404Inquilino no encontradoURL base de cartera incorrecta o inquilino eliminadoVerificar que la URL base sea {company}.appfolio.com/api/v1
409Conflicto de arrendamientoFechas de arrendamiento superpuestas para la misma unidadVerificar arrendamientos existentes en la unidad antes de crear uno nuevo
422Validación fallidaFaltan campos obligatorios en la orden de trabajo o inquilinoIncluir todos los campos obligatorios: unit_id, description, priority
429Demasiadas solicitudesSe excedió el límite de 120 solicitudes/minutoImplementar retroceso exponencial comenzando con 1s de retraso
500Error interno del servidorProblema de la plataforma AppFolioReintentar después de 30s; verificar status.appfolio.com
503Servicio no disponibleVentana 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

EscenarioPatrónRecuperación
Búsqueda de inquilino devuelve 404Buscar por correo electrónico antes de crearUsar endpoint /tenants?email=
Orden de trabajo 422Falta campo de prioridadEstablecer por defecto a normal si no se especifica
Conflicto de fecha de arrendamientoArrendamiento activo superpuestoTerminar arrendamiento existente antes de crear nuevo
Falla parcial en importación masivaAlgunos registros rechazadosAnalizar matriz de errores, reintentar solo registros fallidos
Token de autenticación expiró a medio lote401 en llamadas subsiguientesReautenticar 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.

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 relacionados