Erros Comuns da AppFolio
Visão Geral
A API Stack da AppFolio alimenta integrações de administração de propriedades para triagem de inquilinos, ordens de serviço, gestão de aluguéis e contabilidade. Cada portfólio opera sob seu próprio subdomínio ({empresa}.appfolio.com), o que significa que uma única integração pode precisar lidar com várias URLs base. Os erros geralmente resultam de configuração de autenticação incorreta, URLs base incorretas por portfólio e violações de lógica de negócios, como registros duplicados de inquilinos ou datas de aluguel conflitantes. Falhas na pesquisa de inquilinos (404) são o problema mais frequente, normalmente causado por direcionamento ao subdomínio de portfólio errado. Esta referência cobre falhas de nível HTTP, erros de validação específicos da administração de propriedades e padrões de recuperação para os problemas mais comuns.
Pré-requisitos
- Um registro de incidente anonimizado contendo o identificador do portfólio, endpoint, código de status, ID de correlação da requisição e janela de tempo; nunca copie cargas de inquilinos ou aluguéis para um ticket compartilhado.
- Acesso ao endpoint correto do portfólio (sandbox ou produção) e um proprietário de credenciais que possa rotacionar ou validar credenciais sem expô-las em logs ou argumentos de comando.
- Uma política de retry limitada, um mecanismo de idempotência para gravações e um caminho de escalação conhecido do operador para estados incertos de inquilino, aluguel ou ordem de serviço.
Instruções
- Classifique a resposta por autenticação, limite de taxa, validação ou falha de servidor e preserve apenas os campos de diagnóstico anonimizados.
- Verifique a URL base do portfólio antes de alterar credenciais ou tentar novamente um
404; um ID de inquilino válido em outro portfólio não é evidência de ausência. - Para
409ou falhas de gravação parcial, consulte o registro canônico e use a chave de idempotência da operação ou revisão do operador antes de emitir outra gravação. - Respeite
Retry-Afterpara429e pare após o orçamento de retry configurado; pause o lote em5xxou resultados de gravação desconhecidos.
Referência de Erros
| Código | Mensagem | Causa | Correção |
|---|---|---|---|
401 | Não autorizado | Par client_id/secret inválido ou rotacionado | Regenerar credenciais no portal de parceiros AppFolio Stack |
403 | Proibido | Conta não aprovada como parceiro Stack | Completar inscrição de parceiro em appfolio.com/stack |
404 | Inquilino não encontrado | URL base do portfólio errada ou inquilino excluído | Verificar se a URL base é {empresa}.appfolio.com/api/v1 |
409 | Conflito de aluguel | Datas de aluguel sobrepostas para a mesma unidade | Verificar aluguéis existentes na unidade antes de criar novo |
422 | Falha de validação | Campos obrigatórios ausentes na ordem de serviço ou inquilino | Incluir todos os campos obrigatórios: unit_id, description, priority |
429 | Muitas requisições | Excedido o limite de 120 requisições/minuto | Implementar backoff exponencial começando com atraso de 1s |
500 | Erro interno do servidor | Problema na plataforma AppFolio | Tentar novamente após 30s; verificar status.appfolio.com |
503 | Serviço indisponível | Janela de manutenção (tipicamente fins de semana) | Tentar novamente com backoff; inscrever-se no calendário de manutenção |
Manipulador de Erros
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 exceed", category: "rate_limit" };
}
if (status === 404 || status === 409 || status === 422) {
return { code: status, message: body, category: "validation" };
}
return { code: status, message: body, category: "server" };
}
Guia de Depuração
Erros de Autenticação
A AppFolio usa HTTP Basic Auth com client_id:client_secret. Verifique se as credenciais não estão codificadas em URL. Cada portfólio tem sua própria URL base -- confirme se você está direcionando o subdomínio correto {empresa}.appfolio.com. As credenciais são rotacionadas com alterações na aprovação do parceiro.
Erros de Limite de Taxa
A API Stack impõe 120 requisições/minuto por chave de API. Agrupe pesquisas de inquilinos em vez de chamadas individuais. Use o valor do cabeçalho Retry-After quando presente. Endpoints em massa (ex.: /properties?page=1&per_page=100) reduzem significativamente a contagem de chamadas. Os limites de taxa são por chave, não por portfólio, então integrações com múltiplos portfólios compartilham o mesmo orçamento.
Erros de Validação
A criação de ordem de serviço requer unit_id, description e priority. A criação de inquilino requer first_name, last_name e email. A criação de aluguel falha com 409 se as datas se sobrepuserem a um aluguel ativo existente na mesma unidade -- consulte os aluguéis atuais primeiro. As datas de mudança devem estar no formato ISO 8601 válido. IDs de unidade são específicos do portfólio e não podem ser reutilizados entre subdomínios.
Tratamento de Erros
| Cenário | Padrão | Recuperação |
|---|---|---|
| Pesquisa de inquilino retorna 404 | Pesquisar por email antes de criar | Usar endpoint /tenants?email= |
| Ordem de serviço 422 | Campo priority ausente | Definir como normal se não especificado |
| Conflito de data de aluguel | Aluguel ativo sobreposto | Encerrar aluguel existente antes de criar novo |
| Falha parcial em importação em massa | Alguns registros rejeitados | Analisar array de erros, tentar novamente apenas registros com falha |
| Token de autenticação expirado no meio do lote | 401 em chamadas subsequentes | Reautenticar e retomar do último deslocamento |
Diagnóstico Rápido
# Verificar conectividade da API sem colocar credenciais Basic Auth em 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"
Saída
- Uma classificação anonimizada da falha e o contexto do portfólio verificado
- Uma decisão de recuperação limitada: configuração correta, atraso/retry, reconciliação, rotação através do proprietário da credencial, ou escalação de um resultado de gravação desconhecido
- Um recibo de incidente que identifica o lote afetado sem reter dados de inquilino, aluguel ou credenciais
Exemplos
Quando uma importação de ordem de serviço recebe 429, pare de despachar novos registros, mantenha o cursor do lote e as chaves de idempotência, e aguarde a janela de retry fornecida pelo servidor antes de retomar no mesmo registro. Para um conflito de aluguel 409, consulte o aluguel atual da unidade através do portfólio correto e encaminhe o resultado para um operador autorizado, em vez de encerrar ou substituir um aluguel automaticamente. Se a leitura de acompanhamento não estiver disponível ou o resultado de uma gravação anterior for desconhecido, coloque esse registro em quarentena e continue apenas com trabalho seguro não relacionado.
Recursos
Próximos Passos
Consulte appfolio-debug-bundle.