Erreurs

Deux familles d'erreurs

Une réponse en erreur vient soit du GeoService lui-même, soit du moteur qui a traité la requête. Le type de contenu permet de les distinguer à coup sûr :

Exception : hexodos. Le moteur des cellules H3 écrit ses erreurs au même format que le GeoService, application/problem+json. Elles se reconnaissent à l'en-tête X-GGO-Upstream: hexodos:… et à leur code, listé plus bas ; le code de lecture ci-dessous les traite sans changement.

Une recherche sans résultat n'est pas une erreur : la réponse est 200, avec une liste vide.

Les erreurs du GeoService

Elles suivent la norme RFC 9457 « Problem Details for HTTP APIs », un format JSON standard que de nombreuses bibliothèques savent lire.

{
  "type": "tag:galigeo.com,2026:geoservice:unauthorized",
  "title": "Authentification requise",
  "status": 401,
  "detail": "Clé d'API absente ou invalide.",
  "instance": "/v2/routing/status",
  "code": "unauthorized"
}

Codes d'erreur du GeoService

Trop de requêtes : 429

Le nombre de requêtes par seconde est limité pour chaque client. Au-delà, la réponse est 429 Too Many Requests, renvoyée avant même d'atteindre le GeoService : son corps n'est pas au format application/problem+json. Testez donc le code HTTP, pas le corps.

Les erreurs des moteurs

Une requête que le moteur refuse reçoit son erreur telle quelle, en général avec le code 400. L'en-tête X-GGO-Upstream indique quel moteur a répondu.

Pour les itinéraires, toutes les erreurs de requête partagent le code HTTP 400 : c'est error_code qui les distingue. Les principaux codes sont listés dans Itinéraires › Limites et erreurs.

Les erreurs d'hexodos

Les erreurs des fonctions /v2/hexodos/* sont au format Problem Details ci-dessus. Leur instance est le chemin de la fonction dans le moteur (/route, /isochrone) et leur detail ne reprend jamais une valeur envoyée : il nomme le champ en cause.

Le détail de chaque cas est dans Cellules H3 › Erreurs.

Les erreurs de l'ancienne API /services

L'ancienne API, dépréciée, traduit toutes les erreurs au format du GeoService, celles des moteurs comprises. Là où les routes /v2 de géocodage et d'itinéraires transmettent l'erreur du moteur telle quelle, elle renvoie donc trois codes : 400 invalid_parameter (paramètre invalide ou limite dépassée), 422 route_impossible (aucun itinéraire possible) et 502 upstream_invalid_response (réponse du moteur inexploitable). Les deux premiers existent aussi sur /v2/hexodos/*, ci-dessus ; le troisième n'existe que sur /services. Leur détail est dans Ancienne API › Erreurs ; leurs équivalents en v2, dans le guide de migration.

Gérer les erreurs dans votre code

Un schéma qui couvre les deux familles : lire le code d'une erreur du GeoService, sinon le corps brut de l'erreur du moteur.

class GeoServiceError extends Error {
  constructor(status, code, detail) {
    super(`${status} ${code}: ${detail}`);
    Object.assign(this, { status, code, detail });
  }
}

async function readResponse(res) {
  if (res.ok) return res.json();
  const type = res.headers.get("Content-Type") || "";
  if (type.startsWith("application/problem+json")) {
    // Erreur du GeoService : tester problem.code
    const problem = await res.json();
    throw new GeoServiceError(res.status, problem.code, problem.detail);
  }
  // Erreur du moteur (ou 429) : corps au format du moteur
  throw new GeoServiceError(res.status, "engine_error", await res.text());
}

import httpx


class GeoServiceError(Exception):
    def __init__(self, status: int, code: str, detail: str):
        super().__init__(f"{status} {code}: {detail}")
        self.status, self.code, self.detail = status, code, detail


def read_response(r: httpx.Response):
    if r.is_success:
        return r.json()
    if r.headers.get("Content-Type", "").startswith("application/problem+json"):
        # Erreur du GeoService : tester problem["code"]
        problem = r.json()
        raise GeoServiceError(r.status_code, problem["code"], problem["detail"])
    # Erreur du moteur (ou 429) : corps au format du moteur
    raise GeoServiceError(r.status_code, "engine_error", r.text)