Quotas e limites de taxa

A API do FreeMaint aplica uma quota diária por empresa, reposta à meia-noite UTC. O limite depende do seu plano; os contadores e o saldo restante são expostos em 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 partilham 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 plano
• X-RateLimit-Remaining — chamadas restantes hoje (diminui a cada chamada contabilizada na quota)
• X-RateLimit-Reset — marca temporal Unix da meia-noite UTC (próxima reposição)

O que não conta

Apenas /public-api/whoami é gratuito: não desconta do seu contador, pelo que pode verificar uma chave e o respetivo plano sem gastar quota. Tudo o que passa por /api/v1/graphql é contabilizado, incluindo a query whoami, tal como o endpoint de ingestão de energia.

O que conta como uma chamada

O contador incrementa por OPERAÇÃO, não por pedido HTTP. Agrupar 50 mutações com alias num único pedido consome à mesma 50 unidades. Agrupar poupa idas e voltas à rede, nunca quota. Para manter económica uma sincronização periódica, traga apenas o que mudou com parts(updatedSince: "...") em vez de reler todo o catálogo.

Quando excede o limite

Assim que 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 estado 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.