Fehler

Fehler sind JSON wie alles andere, mit einem passenden HTTP-Status und einem Code, auf den Sie verzweigen können. Die Meldung ist ein Satz für Ihre Logs, nicht für Ihre Nutzer; ihr Wortlaut kann sich ändern, der Code nie.

Die Fehlerhülle

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "Parameter 'lat' must be a number between -90 and 90.",
    "param": "lat"
  }
}

param ist vorhanden, wenn ein bestimmter Parameter das Problem verursacht hat. X-Request-Id wird auch bei Fehlerantworten gesetzt; geben Sie sie an, wenn Sie den Support kontaktieren.

Codes

HTTP	`code`	Wann	Was zu tun ist
400	`invalid_request`	Ein Pflichtparameter fehlt, ein Wert ist fehlerhaft oder außerhalb des gültigen Bereichs, mehr als 100 Punkte oder Adressen in einem Batch, mehr als 10 angeforderte Ergebnisse.	Korrigieren Sie die Anfrage. Nicht unverändert wiederholen.
401	`missing_key`	Es wurde kein Schlüssel gesendet, und der Zugang ohne Schlüssel ist auf diesem Server abgeschaltet. Standardmäßig ist er eingeschaltet, und eine Anfrage ohne Schlüssel wird einfach beantwortet.	Senden Sie einen Schlüssel als `X-API-Key`, als Bearer-Token oder als `key=`.
429	`quota_exceeded`	Die Adresse hat ihre 2.500 kostenlosen Anfragen für heute ohne Schlüssel aufgebraucht.	Warten Sie auf das Zurücksetzen (`Retry-After` und `X-Quota-Reset` sagen, wann), oder senden Sie einen Schlüssel mit Guthaben oder einem Unlimited-Paket.
401	`invalid_key`	Der Schlüssel existiert nicht.	Prüfen Sie auf Tippfehler oder eine unvollständige Kopie.
401	`key_revoked`	Der Schlüssel wurde im Dashboard widerrufen.	Verwenden Sie einen aktuellen Schlüssel.
402	`no_credits`	Das kostenlose Tageskontingent des Schlüssels ist aufgebraucht und das Guthaben des Kontos ist leer.	Laden Sie im Dashboard Guthaben auf, per Karte oder Krypto, oder warten Sie auf das Zurücksetzen.
403	`key_ip_limit`	Alle IP-Plätze dieses Schlüssels sind vorerst von anderen Adressen belegt.	Verwenden Sie einen der Rechner, die einen Platz belegen, geben Sie diesem Rechner einen eigenen Schlüssel oder fügen Sie ein Paket hinzu. Siehe IP-Plätze.
403	`account_suspended`	Das Konto ist gesperrt.	Prüfen Sie Ihre E-Mails von uns oder eröffnen Sie ein Ticket.
404	`not_found`	Der Pfad existiert nicht. Eine Abfrage ohne Treffer ist `200` mit leeren Ergebnissen, nicht `404`.	Prüfen Sie den Pfad und das Versionspräfix.
500	`server_error`	Auf unserer Seite ist etwas kaputtgegangen.	Nach einer Sekunde einmal wiederholen. Der Fehler wird protokolliert und alarmiert uns. Wird nicht gezählt.
503	`unavailable`	Ein Backend ist vorübergehend nicht verfügbar.	Mit Backoff wiederholen. Wird nicht gezählt.

Was keine Fehler sind

Keine Ergebnisse. Eine Geokodierung von Kauderwelsch liefert 200 mit "results": []. Eine Reverse-Geokodierung im Ozean liefert 200 mit "result": null. Beides zählt als Anfrage.
Geringe Genauigkeit. Ein Ergebnis mit "precision": "admin", obwohl Sie ein Haus wollten, ist eine erfolgreiche Anfrage, die weniger gefunden hat als erhofft. Prüfen Sie das Feld.
Private IP-Adressen. Eine Abfrage von 10.0.0.1 liefert 200 mit "is_private": true und ohne Standort.

Fehler auf den Drop-in-Hosts

Die Kompatibilitäts-Hosts geben Fehler in der Struktur zurück, die der ursprüngliche Anbieter verwendet, sodass die bestehende Fehlerbehandlung funktioniert. Zum Beispiel ist ein leeres Guthaben "status": "OVER_QUERY_LIMIT" mit HTTP 200 auf gapi.mygeocode.com, "statusCode": 429 in der Bing-Hülle auf bing.mygeocode.com und {"status":"fail","message":"quota"} auf ipapi.mygeocode.com; ein ungültiger Schlüssel ist jeweils REQUEST_DENIED, 401 und invalid key. Die Header X-Quota-* werden trotzdem auf jedem Host gesendet, sodass Sie den tatsächlichen Stand aus den Headern lesen können, wenn Sie möchten.

Eine sinnvolle Strategie zur Fehlerbehandlung

def call(url, params, tries=3):
    for attempt in range(tries):
        r = session.get(url, params=params, timeout=10)
        if r.status_code == 200:
            return r.json()
        body = r.json()
        code = body["error"]["code"]
        if r.status_code in (500, 503):
            time.sleep(0.2 * (2 ** attempt))
            continue
        # no_credits, key_ip_limit, invalid_request, invalid_key: retrying will not help
        raise ApiError(code, body["error"]["message"], r.headers.get("X-Request-Id"))
    raise ApiError("retries_exhausted", "Gave up after %d attempts" % tries, None)