Limites de Taxa do AppFolio
Visão Geral
A API Stack do AppFolio impõe limites de taxa por parceiro para proteger a infraestrutura compartilhada de gerenciamento de propriedades. Operações de alto volume, como importações em massa de inquilinos, sincronizações de aluguel e atualizações em lote de ordens de serviço, podem esgotar rapidamente as cotas. Gerentes de propriedades que executam sincronizações noturnas de portfólio em centenas de unidades precisam fazer throttling cuidadosamente, especialmente no final do mês, quando renovações de contratos de locação e processamento de pagamentos aumentam simultaneamente.
Pré-requisitos
- Um limite verificado por endpoint a partir do contrato atual de parceiro AppFolio ou cabeçalhos de resposta; não confie em um valor genérico de taxa para gravações de inquilinos.
- Cursors de lote persistidos, chaves de idempotência para cada gravação e uma política operacional para pausar cargas de trabalho sensíveis à segurança, como as de final de mês.
- Um fixture de staging e um proprietário de orçamento de requisições que possa provar tentativas, comportamento de
429e tratamento de gravações desconhecidas sem tocar em inquilinos de produção.
Instruções
- Selecione o teto do limitador para o endpoint específico e mantenha a concorrência abaixo do menor limite aplicável de portfólio ou parceiro.
- Adquira um token antes de cada requisição, respeite o
Retry-Aftere limite tentativas com jitter para falhas transitórias do provedor. - Processe gravações a partir de um cursor persistido com chaves de idempotência; nunca repita uma criação de inquilino só porque a resposta foi perdida.
- Pause e escale lotes que esgotem o orçamento de tentativas, atinjam uma janela de manutenção ou tenham um resultado de gravação desconhecido.
Referência de Limite de Taxa
| Endpoint | Limite | Janela | Escopo |
|---|---|---|---|
| Lista/obter propriedades | 120 req | 1 minuto | Por chave de parceiro |
| Criar/atualizar inquilino | 30 req | 1 minuto | Por chave de parceiro |
| Ordens de serviço | 60 req | 1 minuto | Por chave de parceiro |
| Exportação de dados em massa | 5 req | 1 hora | Por chave de parceiro |
| Registro de webhooks | 10 req | 1 minuto | Por chave de parceiro |
Implementação do Limitador de Taxa
class AppFolioRateLimiter {
private tokens: number;
private lastRefill: number;
private readonly maxTokens: number;
private readonly refillRate: number; // tokens por ms
constructor(maxPerMinute: number) {
this.maxTokens = maxPerMinute;
this.tokens = maxPerMinute;
this.lastRefill = Date.now();
this.refillRate = maxPerMinute / 60_000;
}
async acquire(): Promise<void> {
for (;;) {
this.refill();
if (this.tokens >= 1) {
this.tokens -= 1;
return;
}
// Aguarda até que o próximo token esteja disponível; nenhuma requisição posterior é necessária para
// acordar este chamador.
const waitMs = Math.max(1, Math.ceil((1 - this.tokens) / this.refillRate));
await new Promise(resolve => setTimeout(resolve, waitMs));
}
}
private refill() {
const now = Date.now();
this.tokens = Math.min(this.maxTokens, this.tokens + (now - this.lastRefill) * this.refillRate);
this.lastRefill = now;
}
}
const limiter = new AppFolioRateLimiter(25); // configurar por contrato de endpoint
Estratégia de Tentativas
async function appfolioRetry<T>(fn: () => Promise<Response>, maxRetries = 4): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
await limiter.acquire();
const res = await fn();
if (res.ok) return res.json();
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get("Retry-After") || "10", 10);
const delay = retryAfter * 1000 + Math.random() * 2000;
await new Promise(r => setTimeout(r, delay));
continue;
}
if (res.status >= 500 && attempt < maxRetries) {
await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
continue;
}
throw new Error(`AppFolio API ${res.status}: ${await res.text()}`);
}
throw new Error("Máximo de tentativas excedido");
}
Processamento em Lote
async function batchSyncTenants(tenants: any[], batchSize = 25) {
const results: any[] = [];
for (let i = 0; i < tenants.length; i += batchSize) {
const batch = tenants.slice(i, i + batchSize);
const batchResults = await Promise.all(
batch.map(t => appfolioRetry(() =>
fetch(`${BASE}/api/v1/tenants`, {
method: "POST", headers, body: JSON.stringify(t),
})
))
);
results.push(...batchResults);
if (i + batchSize < tenants.length) await new Promise(r => setTimeout(r, 2000));
}
return results;
}
Tratamento de Erros
| Problema | Causa | Correção |
|---|---|---|
| 429 Muitas Requisições | Limite de taxa do parceiro excedido | Backoff usando cabeçalho Retry-After |
| 403 na exportação em massa | Cota horária de exportação atingida | Enfileirar exportações com espaçamento de 15 min |
| Timeout na lista de propriedades | Portfólio grande (500+ unidades) | Paginar com per_page=50 |
| 409 Conflito na atualização de inquilino | Gravação simultânea no mesmo inquilino | Tentar novamente com ETag nova |
| 503 durante manutenção | Janela noturna agendada (2-4 AM PT) | Pular requisições, tentar novamente após a janela |
Saída
- Um limitador auto-agendável e específico por endpoint que não pode deixar trabalho enfileirado preso
- Resultados de tentativas limitados com evidência de
Retry-Aftere dados de falha editados - Uma decisão de lote persistida: concluído, pausado para tentativa futura, ou colocado em quarentena para reconciliação pelo operador
Exemplos
Para um lote de atualização de inquilinos no sandbox, configure o limitador abaixo do teto documentado de gravação de inquilinos, processe um registro por vez com chaves de idempotência e preserve o cursor após cada resultado confirmado. Induza um 429 para provar que os chamadores esperam e retomam sem uma requisição adicional, depois induza uma resposta perdida para provar que o registro é colocado em quarentena, e não repetido cegamente. Se os cabeçalhos de taxa entrarem em conflito com o teto configurado, as tentativas se esgotarem ou a manutenção começar, pause o lote e entregue o cursor ao proprietário.
Recursos
Próximos Passos
Consulte appfolio-performance-tuning.