Die Nutzung Ihres Schlüssels überwachen, bevor Sie an ein Limit stoßen
Wenn Sie Ihre Kontingent-Header laufend beobachten, wissen Sie, wann ein Limit näher rückt, lange bevor eine Anfrage tatsächlich abgelehnt wird.
Die Header X-Quota-Used und X-Quota-Limit richtig lesen
Jede Antwort der API, ob erfolgreich oder nicht, enthält eine Reihe von Headern, die genau beschreiben, wo Sie im Verhältnis zu Ihrem Kontingent stehen. Um sie richtig zu lesen, müssen Sie verstehen, was jeder einzelne zählt.
Das zentrale Paar
X-Quota-Limit ist die Größe Ihres aktuellen Kontingents, entweder das kostenlose Tageskontingent oder das effektive Limit unter einem Unlimited-Paket. X-Quota-Used gibt an, wie viele Anfragen im aktuellen Zeitraum bisher auf dieses Kontingent angerechnet wurden. Das eine vom anderen von Hand abzuziehen ist unnötig, da X-Quota-Free-Remaining das bereits für Sie erledigt.
HTTP/1.1 200 OK
X-Quota-Limit: 2500
X-Quota-Used: 1840
X-Quota-Free-Remaining: 660
X-Quota-Network-Used: 1840
X-Credits-Remaining: 0.00
X-Key-IPs-Used: 1
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00ZSchlüsselnutzung und Netzwerknutzung
X-Quota-Used spiegelt die Nutzung Ihres Schlüssels wider, während X-Quota-Network-Used die Nutzung aus dem umgebenden Netzwerk abbildet, da das kostenlose Kontingent zwischen allen IPv4-Adressen im selben /24 und allen IPv6-Adressen im selben /48 geteilt wird, unabhängig davon, ob ein Schlüssel beteiligt ist. Wird ein Schlüssel von mehreren Servern hinter demselben Adressblock aufgerufen, steigt der Netzwerkwert schneller, als es ein einzelner Server aufgrund seines eigenen Traffics erwarten würde.
Das Paar für IP-Plätze
X-Key-IPs-Used und X-Key-IPs-Limit beschreiben etwas ganz anderes: wie viele verschiedene Quelladressen diesen Schlüssel in letzter Zeit verwendet haben, gemessen am gleitenden Limit von zwei oder drei Adressen pro Schlüssel. Ein Schlüssel, der von einem einzigen Server aufgerufen wird, zeigt hier konstant 1. Ein Schlüssel, der auf mehreren voneinander unabhängigen Servern genutzt wird oder in ein Skript kopiert wurde, das am Ende auf vielen Maschinen läuft, nähert sich dem Limit. Das sollten Sie getrennt von Ihrem Anfragekontingent beobachten, denn es kann einen Schlüssel sperren, selbst wenn noch reichlich kostenlose Anfragen übrig sind.
Guthaben und Zeitpunkt des Zurücksetzens
X-Credits-Remaining zeigt Ihr Prepaid-Guthaben, sobald Sie das kostenlose Kontingent überschritten haben und Guthaben zu 0,0001 € pro Anfrage verbrauchen. X-Quota-Reset sagt Ihnen genau, wann das aktuelle Tageskontingent zurückgesetzt wird, was zuverlässiger ist, als eine feste Uhrzeit nach Ihrer eigenen Uhr anzunehmen.
Was Sie auf Basis dieser Header bauen sollten
Ein Dashboard, ein Alarm oder einfach eine Logzeile, die diese Header nach jedem Aufruf ausliest, liefert Ihnen ein Live-Bild der Nutzung ohne separaten Reporting-Aufruf, da die Zahlen mit der Antwort kommen, die Sie ohnehin angefordert haben. Das Auslesen kostet nichts extra, da sie bei jeder Anfrage mitkommen, die Sie ohnehin gesendet haben, ob diese Anfrage erfolgreich war oder als Fehler zurückkam.
Ein Fehler, den Sie vermeiden sollten
Wer diese Header nur ausliest, wenn etwas schiefgeht, erfährt von einem Kontingentproblem im selben Moment wie seine Nutzer. Protokollieren Sie mindestens X-Quota-Free-Remaining und X-Credits-Remaining in regelmäßigen Abständen oder in einer Integration mit wenig Traffic nach jedem Aufruf, damit sich ein langsamer Anstieg in Richtung Limit als Trend in einem Dashboard zeigt und nicht als plötzliche Serie von 429-Antworten.
Die Kontingent-Header in jeder Antwort zu lesen, statt auf einen 429 zu warten, um ein Problem zu bemerken, ist der Unterschied zwischen einer kontrollierten Verlangsamung und einer überraschenden. Die vollständige Header-Liste ist auf der Seite zu Ratenlimits dokumentiert.