Erreurs

Les erreurs sont en JSON, comme tout le reste, avec un statut HTTP correspondant et un code sur lequel vous pouvez vous baser. Le message est une phrase destinée à vos journaux, pas à vos utilisateurs ; sa formulation peut changer, le code jamais.

L'enveloppe d'erreur

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

param est présent lorsqu'un paramètre précis a causé le problème. X-Request-Id est aussi défini sur les réponses d'erreur ; indiquez-le si vous contactez le support.

Codes

HTTP	`code`	Quand	Que faire
400	`invalid_request`	Un paramètre obligatoire est absent, une valeur est mal formée ou hors limites, plus de 100 points ou adresses dans un lot, plus de 10 résultats demandés.	Corrigez la requête. Ne réessayez pas sans la modifier.
401	`missing_key`	Aucune clé n'a été envoyée et l'accès sans clé est désactivé sur ce serveur. Par défaut, il est activé et une requête sans clé reçoit simplement une réponse.	Envoyez une clé dans `X-API-Key`, sous forme de jeton Bearer ou dans `key=`.
429	`quota_exceeded`	L'adresse a utilisé ses 2 500 requêtes gratuites du jour sans clé.	Attendez la remise à zéro (`Retry-After` et `X-Quota-Reset` indiquent quand), ou envoyez une clé disposant de crédit ou d'un forfait Unlimited.
401	`invalid_key`	La clé n'existe pas.	Vérifiez qu'il n'y a pas de faute de frappe ou de copie tronquée.
401	`key_revoked`	La clé a été révoquée dans le tableau de bord.	Utilisez une clé valide.
402	`no_credits`	Le quota gratuit du jour de la clé est épuisé et le solde de crédit du compte est vide.	Ajoutez du crédit dans le tableau de bord, par carte ou en crypto, ou attendez la remise à zéro.
403	`key_ip_limit`	Tous les emplacements IP de cette clé sont occupés par d'autres adresses pour un certain temps.	Utilisez l'une des machines qui occupent un emplacement, donnez à cette machine sa propre clé ou ajoutez un forfait. Voir emplacements IP.
403	`account_suspended`	Le compte est suspendu.	Consultez nos e-mails ou ouvrez un ticket.
404	`not_found`	Le chemin n'existe pas. Une requête sans correspondance renvoie `200` avec des résultats vides, pas `404`.	Vérifiez le chemin et le préfixe de version.
500	`server_error`	Un problème est survenu de notre côté.	Réessayez une fois après une seconde. L'erreur est journalisée et nous alerte. Non comptée.
503	`unavailable`	Un service interne est temporairement indisponible.	Réessayez avec un délai croissant. Non comptée.

Ce qui n'est pas une erreur

Aucun résultat. Un géocodage direct de charabia renvoie 200 avec "results": []. Un géocodage inverse en plein océan renvoie 200 avec "result": null. Les deux comptent comme une requête.
Précision faible. Un résultat avec "precision": "admin" alors que vous vouliez une maison est une requête réussie qui a trouvé moins que prévu. Vérifiez le champ.
Adresses IP privées. Rechercher 10.0.0.1 renvoie 200 avec "is_private": true et aucune localisation.

Erreurs sur les hôtes compatibles

Les hôtes compatibles renvoient les erreurs dans le format qu'utilise le fournisseur d'origine, si bien que la gestion existante fonctionne. Par exemple, un solde de crédit vide donne "status": "OVER_QUERY_LIMIT" avec HTTP 200 sur gapi.mygeocode.com, "statusCode": 429 dans l'enveloppe Bing sur bing.mygeocode.com, et {"status":"fail","message":"quota"} sur ipapi.mygeocode.com ; une clé invalide donne respectivement REQUEST_DENIED, 401 et invalid key. Les en-têtes X-Quota-* sont envoyés sur tous les hôtes dans tous les cas, vous pouvez donc lire l'état réel dans les en-têtes si vous le souhaitez.

Une stratégie de gestion raisonnable

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)