Codes d'erreur

L'API utilise les codes HTTP standards. Tous les corps de réponse en erreur suivent le format {"detail": "<description>"} (ou un tableau pour les erreurs de validation).

Vue d'ensemble

Code	Famille	Cause typique
200	OK	Succès, lire le corps
400	Client	Requête malformée (query trop courte, JSON invalide)
401	Auth	Clé manquante ou invalide
403	Auth	Plan insuffisant pour cet endpoint
404	Client	Ressource inexistante (identifiant BAN inconnu)
422	Client	Validation Pydantic (paramètres incohérents)
429	Quota	Quota mensuel dépassé
500	Serveur	Erreur interne (parser, Meilisearch, moteur de traitement)
503	Serveur	Service d'authentification temporairement indisponible

Réussite particulière : 200 OK sans match

Une recherche qui ne retourne aucun résultat reste un succès HTTP. Le champ status du corps signale la situation :

{
  "status": "no_results",
  "message": "No verified match found",
  "matches": []
}

De même pour une requête trop courte sur /address/autocomplete :

{
  "status": "TOO_SHORT",
  "message": "The request is too short, complete your input",
  "suggestions": []
}

Côté code client : testez systématiquement status avant de consommer suggestions / matches / results.

400 Bad Request

La requête est malformée : query q manquante, JSON corps non valide, paramètre obligatoire absent.

{ "detail": "Request too short or invalid" }

Action : corriger la requête côté client. Ces erreurs ne sont pas comptées dans le quota.

401 Unauthorized

Le header Authorization est absent, mal formé, ou la clé n'est plus valide (révoquée, compte fermé).

{ "detail": "API key required. Please provide a valid API key in the Authorization header." }

{ "detail": "Invalid API key" }

Action : vérifier le header (préfixe Bearer obligatoire, sans guillemets autour de la clé), vérifier que la clé n'a pas été révoquée dans l'espace client.

403 Forbidden

La clé est valide mais son plan ne donne pas accès à l'endpoint appelé. Cas typique : appel de /route/compute avec une clé Growth (réservé Business).

{ "detail": "Your plan (GROWTH) does not have access to this service. Please upgrade your plan." }

Action : upgrader le plan, ou utiliser un endpoint accessible — voir Plans & quotas.

404 Not Found

L'identifiant fourni (typiquement à GET /address/view/{id}) ne correspond à aucune adresse de la base BAN.

Action : vérifier l'identifiant. Les IDs peuvent évoluer entre deux millésimes BAN si une voie est renommée — préférer toujours id_ban au champ id interne pour le stockage long terme.

422 Unprocessable Entity

Validation Pydantic — les paramètres passent le format mais violent une règle métier. Le corps liste les erreurs en détail.

{
  "detail": [
    {
      "type": "value_error",
      "loc": [],
      "msg": "Value error, population_min must be less than or equal to population_max",
      "input": { "population_min": 1500, "population_max": 150 }
    }
  ]
}

Côté /route/*, un 422 peut aussi signifier qu'une adresse fournie en bornes n'a pas pu être résolue contre la BAN.

Action : lire msg et loc, corriger le payload.

429 Too Many Requests

Le quota mensuel est dépassé. Concerne d'abord le plan Discovery (5 000 requêtes / mois — hard cap) ; les autres plans suivent les volumes contractuels.

{ "detail": "Rate limit exceeded. Max allowed usage for plan DISCOVERY is 5000 requests." }

{ "detail": "Your plan (STARTER) has exceeded the rate limit for this service. Please upgrade your plan." }

Action : attendre la prochaine période de facturation, ou upgrader. Il n'y a pas de header Retry-After pour l'instant — le quota se réinitialise au début de la période mensuelle de votre abonnement.

500 Internal Server Error

Erreur côté API : parser d'adresses indisponible, Meilisearch en surcharge, moteur de traitement injoignable sur les endpoints de routage.

Action : retry avec un backoff exponentiel (1s, 3s, 9s, 27s…). Si les 500 persistent au-delà de quelques minutes, contactez-nous avec les X-Request-ID des appels concernés (à venir).

503 Service Unavailable

Le service d'authentification (validation de votre clé) est temporairement injoignable. L'API préfère échouer explicitement plutôt que de servir des requêtes sans vérifier l'identité.

{ "detail": "Authentication service unavailable" }

Action : retry avec backoff exponentiel. La durée typique d'indisponibilité est de l'ordre de la seconde — si ça persiste, contactez-nous.

Pattern de retry recommandé

Pour les codes 500, 502, 503, 504 : backoff exponentiel avec jitter. Pour 429 : pas de retry — c'est une erreur structurelle, attendez le reset. Pour 4xx (autre que 429) : pas de retry — corrigez la requête.

import time, random, requests

def call_with_retry(url, headers, params=None, json=None, max_attempts=4):
    for attempt in range(max_attempts):
        r = requests.get(url, headers=headers, params=params, timeout=10) \
            if json is None else \
            requests.post(url, headers=headers, json=json, timeout=10)
        if r.status_code < 500 and r.status_code != 429:
            return r          # succès ou erreur cliente, on rend
        if r.status_code == 429 or attempt == max_attempts - 1:
            return r          # quota: pas de retry. Dernier essai: rend.
        sleep = (2 ** attempt) + random.random()
        time.sleep(sleep)     # 1s, 3s, 7s, ... avec jitter

Prochains pas

• Authentification — détails 401/403
• Plans & quotas — comprendre les 403/429
• Référence complète — voir le détail par endpoint