Das Problem mit API-Schlüsseln, die nie ablaufen
Ein Schlüssel, der vor Jahren ausgestellt, nie rotiert wurde und heute noch gültig ist, ist keine Bequemlichkeit. Er ist ein Risiko, das sich seit Jahren niemand mehr angesehen hat.
Warum wir unsere Fehlercodes veröffentlichen, statt sie zu verstecken
Eine fehlgeschlagene API-Anfrage ist ohnehin schon ein schlechter Moment im Tag eines Menschen. Es wird schlimmer, wenn der zurückgegebene Fehlercode nirgends erklärt ist und der Entwickler bei der Fehlersuche raten muss, ob ein 400 einen fehlerhaften Parameter bedeutet, ein fehlendes Pflichtfeld oder etwas völlig anderes, das zufällig denselben Statuscode wie drei andere, unzusammenhängende Probleme hat. Ein undokumentierter Fehler ist nicht nur lästig. Er macht aus einer Korrektur von fünf Minuten eine Untersuchung mit offenem Ende, die manchmal in einem Support-Ticket endet, das sich durch das Lesen einer Seite hätte vermeiden lassen, die es hätte geben sollen.
Wir veröffentlichen unsere Fehlercodes klar in der Fehlerdokumentation und führen auf, was jeder einzelne tatsächlich bedeutet und was ihn häufig verursacht, neben den Seiten zu Authentifizierung und Ratenlimits, die die anderen Arten beschreiben, wie eine Anfrage scheitern kann. Das Ziel ist, dass die Antwort, wenn etwas schiefgeht, nur eine Seite entfernt ist und kein Ratespiel auf Basis allgemeiner HTTP-Statuscode-Konventionen, die sich mehr oder weniger sauber auf das übertragen lassen, was unser System konkret getan hat.
Fehlerdetails zu verbergen, auch unbeabsichtigt durch dünne Dokumentation, entspringt manchmal einem vernünftig klingenden Instinkt: Genau offenzulegen, warum eine Anfrage fehlgeschlagen ist, könnte theoretisch jemandem helfen, der eine API nach Schwachstellen abklopft. In der Praxis hält diese Sorge den tatsächlichen Kosten selten stand. Die überwältigende Mehrheit der Menschen, die auf einen Fehlercode stoßen, sind legitime Entwickler, die ihre eigene Integration reparieren wollen, keine Angreifer, die eine Angriffsfläche kartieren. Fehlerdokumentation auf den seltenen böswilligen Akteur auszurichten, auf Kosten der Klarheit für alle anderen, stellt die Abwägung auf den Kopf.
Klar veröffentlichte Fehlercodes haben auch einen Vorteil für die Disziplin beim Design: Sie erzwingen innere Konsistenz. Wenn jeder Fehlercode mit einer klaren Erklärung dokumentiert werden muss, wird es viel schwerer, einen Haufen improvisierter, sich überschneidender Fehlerbedingungen anzusammeln, die nur der ursprüngliche Entwickler vollständig versteht. Das Schreiben der Dokumentation ist nebenbei auch eine Art Code-Review der Fehlerbehandlung selbst, denn ein Fehler, der sich schwer klar erklären lässt, ist oft ein Zeichen dafür, dass die zugrunde liegende Bedingung von vornherein nicht gut durchdacht war.
Fehler im Zusammenhang mit dem Kontingent werden ähnlich behandelt, und zwar über Antwort-Header statt nur über Fehlercodes. Jede Antwort enthält Ihr Kontingentlimit, den Verbrauch, das verbleibende kostenlose Kontingent, den Verbrauch Ihres Netzwerks, das verbleibende Guthaben und den Zeitpunkt des Zurücksetzens, sodass eine Anfrage, die am Kontingent scheitert, überhaupt kein rätselhafter Statuscode ist. Es ist eine Zahl, die Sie vor dem Senden der Anfrage hätten prüfen können und die Sie direkt aus der fehlgeschlagenen Antwort ablesen können.
Nichts davon beseitigt den Frust über eine fehlgeschlagene Anfrage. Es bedeutet nur, dass der Frust bei der Dokumentation enden sollte, mit einer echten Antwort, statt sich in einer Support-Warteschlange fortzusetzen oder in einem Ratespiel quer durch alte Forenbeiträge darüber, was ein Statuscode einer völlig anderen API in einer ähnlich klingenden Situation bedeutet haben könnte.