Kontingente & Ratenlimits

Die FreeMaint-API erzwingt ein tägliches Kontingent pro Unternehmen, das um Mitternacht UTC zurückgesetzt wird. Die Obergrenze hängt von Ihrer Stufe ab; Zähler und verbleibende Werte werden als Antwortheader angezeigt.

Tägliche Obergrenzen

• Core, Starter — 0 (ein API-Schlüssel setzt Business voraus)
• Business — 5.000 Aufrufe/Tag (GraphQL und der Energie-Ingest-Endpunkt teilen sich denselben Zähler)
• Enterprise — 100.000 Aufrufe/Tag
• On-Premise — unbegrenzt (Limit = null)

Antwortheader

• X-RateLimit-Limit – die tägliche Obergrenze Ihrer Stufe
• X-RateLimit-Remaining – heute verbleibende Anrufe (verringert sich bei jedem kontingentgezählten Anruf)
• X-RateLimit-Reset – Unix-Zeitstempel von Mitternacht UTC (nächstes Zurücksetzen)

Was zählt nicht

Nur /public-api/whoami ist kostenlos — es verringert Ihren Zähler nicht, sodass Sie einen Schlüssel und seinen Tarif prüfen können, ohne Kontingent zu verbrauchen. Alles über /api/v1/graphql wird gezählt, auch die whoami-Abfrage, ebenso der Energie-Ingest-Endpunkt.

Was als ein Aufruf zählt

Der Zähler erhöht sich pro OPERATION, nicht pro HTTP-Anfrage. 50 mit Alias gebündelte Mutationen in einer Anfrage verbrauchen weiterhin 50 Einheiten. Bündeln spart also Roundtrips, niemals Kontingent. Damit eine wiederkehrende Synchronisation bezahlbar bleibt, holen Sie mit parts(updatedSince: "...") nur das Geänderte, statt den ganzen Katalog erneut zu lesen.

Wenn Sie die Obergrenze überschreiten

Sobald Ihr Tageslimit erreicht ist, wird jeder weitere Aufruf mit der Meldung „Daily API cap reached“ abgelehnt. Auf den REST-Oberflächen (/public-api/ping, der Energie-Ingest-Endpunkt) ist das ein HTTP 403. Bei GraphQL ist der HTTP-Status 200 und die Ablehnung steht in errors[0].extensions.code = FORBIDDEN, mit originalError.statusCode = 403. Der Zähler wird um 00:00 UTC zurückgesetzt. Es gibt kein weiches Limit, keine Burst-Reserve und kein Minutenfenster — das Fenster ist der Tag.