Codes d'erreur

Liste complète des codes HTTP renvoyés par l'API TMaps, avec leur signification, leur cause typique et le format du body de réponse.

Toutes les erreurs renvoyées par l'API TMaps suivent un format JSON commun et utilisent les codes HTTP standard. Cette page liste les codes que vous pouvez rencontrer et leur signification.

Format des erreurs

Toute réponse d'erreur a un body JSON minimal, encodé en UTF-8 :

{
  "error": "missing api_key"
}

Le champ error contient un message court en anglais, exploitable pour le debug. Ce message peut évoluer dans le temps : ne le parsez pas pour piloter votre logique métier — utilisez le code HTTP.

Codes HTTP

HTTP	Signification	Cause typique	Body de réponse
400	Mauvaise requête	Paramètre obligatoire manquant ou mal formé	`{"error":"missing required param: q"}`
401	Clé API invalide	api_key absent, désactivé ou révoqué	`{"error":"missing api_key"}`
403	Domaine non autorisé	Origin / Referer absent de la liste blanche, ou requête HTTP	`{"error":"domain not authorized"}`
404	Ressource introuvable	Endpoint ou identifiant inexistant	`{"error":"not found"}`
429	Trop de requêtes	Pic ponctuel détecté côté infrastructure (pas de quota par défaut)	`{"error":"rate limited"}`
500	Erreur serveur	Incident interne — réessayer après quelques secondes	`{"error":"internal error"}`

Pas de rate limit applicatif

L'API TMaps n'impose pas de quota ni de rate limit par clé. Le code 429 n'apparaît qu'en cas de protection anti-burst au niveau infrastructure (pic ponctuel) — il est rare en usage normal et résolu par un simple retry with backoff.

Gérer les erreurs côté client

Reconnaître une erreur d'authentification

Les codes 401 et 403 sont des erreurs de configuration, pas d'usage : il ne sert à rien de retenter la requête. Vérifiez plutôt :

401 : la clé est-elle bien renseignée ? Active dans la console ?
403 : le domaine d'appel est-il dans la liste des domaines autorisés ? Si l'appel est server-side (sans Origin), le 403 ne devrait pas se produire.

Stratégie de retry

4xx : ne jamais retenter automatiquement (sauf 429).
429 : retry avec un backoff exponentiel (1 s, 2 s, 4 s) — max 3 tentatives.
5xx : retry avec un backoff exponentiel — max 3 tentatives.

Exemple — wrapper fetch avec retry

async function tmapsFetch(url, options = {}, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);

    // Pas d'erreur → on retourne
    if (res.ok) return res.json();

    // 4xx (sauf 429) → erreur définitive
    if (res.status >= 400 && res.status < 500 && res.status !== 429) {
      const body = await res.json().catch(() => ({}));
      throw new Error(`TMaps ${res.status} — ${body.error ?? 'unknown'}`);
    }

    // 429 ou 5xx → backoff exponentiel
    await new Promise((r) => setTimeout(r, 2 ** i * 1000));
  }
  throw new Error('TMaps: max retries reached');
}