Eine Fehlerantwort ist keine Fußnote einer API, sondern Teil des Vertrags, auf den sich jede Integration genauso verlässt wie auf eine erfolgreiche Antwort. Wir haben das Fehlerformat über alle nativen Endpunkte von My Geocode vereinheitlicht, sodass ein Fehler gleich aussieht, egal welcher Teil der API ihn erzeugt hat.
Ob eine Anfrage an einem fehlenden Parameter, einem ungültigen Schlüssel, einem aufgebrauchten Kontingent oder einer fehlerhaften Koordinate scheitert, die Antwort folgt einer einzigen, vorhersehbaren Struktur. Diese Konsistenz bedeutet, dass Fehlerbehandlungscode, der einmal für einen Endpunkt geschrieben wurde, bei jedem anderen nativen Endpunkt genauso funktioniert, ohne dass für jeden eine eigene Behandlungslogik nötig ist.
Fehler im Zusammenhang mit dem Kontingent verdienen besondere Erwähnung, da sie die häufigste Art sind, auf die eine aktive Integration stößt. Wenn eine Anfrage das Kontingent eines Schlüssels oder eines Netzwerks überschreiten würde, macht die Antwort das deutlich, und die Kontingent-Header, die bereits in jeder Antwort enthalten sind, X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining und die übrigen, zeigen Ihnen genau, wie viel Spielraum vor der fehlgeschlagenen Anfrage verfügbar war. Durch diese Kombination kann ein Client allein anhand der Antwort ein Kontingentproblem von einem Authentifizierungsproblem oder einer fehlerhaften Anfrage unterscheiden, ohne raten zu müssen.
Kompatibilitäts-Hosts sind eine bewusste Ausnahme von dieser Vereinheitlichung, und das aus gutem Grund. Ihr ganzer Zweck ist es, die Anfrage- und Antwortstruktur eines anderen Anbieters exakt nachzubilden, und dazu gehört auch, wie Fehler aussehen. Eine für Bing Maps REST Services geformte Anfrage, die fehlschlägt, erhält weiterhin einen Fehler im eigenen Fehlerformat von Bing, denn genau diese Struktur präzise zu treffen, ob bei Erfolg oder Fehler, ist der ganze Sinn eines Drop-in-Hosts. Die Fehler dort zu vereinheitlichen, würde genau die Kompatibilität zerstören, für die der Host existiert.
Für alles, was gegen unsere nativen Endpunkte gebaut ist, sollte dieses sauberere Format die Fehlerbehandlung spürbar einfacher zu schreiben und zu pflegen machen. Eine einzige Parsing-Routine, ein einziger Satz erwarteter Felder und konsistentes Verhalten bei /v1/forward, /v1/reverse, /v1/ip, /v1/timezone, /v1/elevation, /v1/autocomplete und /v1/postcode gleichermaßen.
Die vollständige Dokumentation des Fehlerformats, einschließlich Feldnamen und häufiger Ursachen, finden Sie unter /docs/errors/. Wenn Ihre Integration derzeit getrennte Zweige zur Fehlerbehandlung für verschiedene native Endpunkte hat, ist jetzt ein guter Zeitpunkt, das auf einen einzigen zu vereinfachen.