Cotas e limites de taxa

A API FreeMaint impõe uma cota diária por empresa, redefinida à meia-noite UTC. O limite depende do seu nível; contadores e restantes são expostos como cabeçalhos de resposta.

Limites diários

• Core, Starter — 0 (uma chave de API exige Business)
• Business — 5.000 chamadas/dia (o GraphQL e o endpoint de ingestão de energia compartilham o mesmo contador)
• Enterprise — 100.000 chamadas/dia
• On-Premise — ilimitado (limite = null)

Cabeçalhos de resposta

• X-RateLimit-Limit — o limite diário do seu nível
• X-RateLimit-Remaining — chamadas restantes hoje (diminui em cada chamada contada por cota)
• X-RateLimit-Reset — carimbo de data/hora Unix da meia-noite UTC (próxima redefinição)

O que não conta

Apenas /public-api/whoami é gratuito: não desconta do seu contador, então você pode verificar uma chave e seu plano sem gastar cota. Tudo o que passa por /api/v1/graphql é contabilizado, inclusive a query whoami, assim como o endpoint de ingestão de energia.

O que conta como uma chamada

O contador incrementa por OPERAÇÃO, não por requisição HTTP. Agrupar 50 mutações com alias em uma única requisição consome os mesmos 50 créditos. Agrupar economiza idas e voltas de rede, nunca cota. Para deixar barata uma sincronização recorrente, traga só o que mudou com parts(updatedSince: "...") em vez de reler o catálogo inteiro.

Quando você excede o limite

Assim que você atinge o limite diário, cada chamada adicional é recusada com a mensagem «Daily API cap reached». Nas superfícies REST (/public-api/ping, o endpoint de ingestão de energia) isso é um HTTP 403. No GraphQL o status HTTP é 200 e a recusa está em errors[0].extensions.code = FORBIDDEN, com originalError.statusCode = 403. O contador reinicia às 00:00 UTC. Não há limite flexível, nem tolerância de rajada, nem janela por minuto: a janela é o dia.