Erreurs

Le format Problem Details et chaque code que l’API peut renvoyer.

Format des erreurs

Chaque erreur est un objet Problem Details (RFC 9457) servi en application/problem+json. Fiez-vous à status et à code ; detail est un texte anglais qui peut changer.

Format des erreurs
Membre	Description
`type`	Toujours `about:blank`.
`title`	Intitulé HTTP standard, en anglais.
`status`	Code HTTP.
`code`	Code stable, lisible par une machine.
`detail`	Explication en anglais, pour le développement.
`request_id`	Identifiant de la requête, aussi dans l’en-tête `X-Request-Id`. Citez-le quand vous signalez un problème.
`errors`	Pour `validation_failed` seulement : les messages par paramètre.

Exemple

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "The API key is invalid or has been revoked.",
  "request_id": "…"
}

Codes d’erreur

Codes d’erreur
Statut	Code	Signification	Que faire
`401`	`missing_api_key`	Aucune clé dans l’en-tête `Authorization`.	Envoyez `Authorization: Bearer` suivi de la clé.
`401`	`invalid_api_key`	Clé inconnue, mal formée, expirée ou révoquée, ou projet inactif.	Vérifiez la clé dans la console ou créez-en une autre.
`403`	`insufficient_scope`	La clé n’a pas l’accès exigé par cette route.	Créez une clé avec cet accès.
`404`	`not_found`	Route inconnue, ou paramètre de chemin hors règles.	Vérifiez le chemin et la méthode.
`404`	`place_not_found`	Aucun lieu avec cette référence dans le catalogue.	Relancez une recherche : les références changent entre catalogues.
`405`	`method_not_allowed`	Méthode HTTP non acceptée.	Utilisez `GET`.
`422`	`validation_failed`	Un paramètre manque ou ne respecte pas ses règles.	Corrigez les paramètres listés dans `errors`.
`429`	`rate_limited`	Limite de débit du projet atteinte.	Attendez le nombre de secondes indiqué par `Retry-After`.
`500`	`internal_error`	Erreur inattendue du service.	Réessayez plus tard avec un délai croissant ; citez le `request_id`.
`503`	`service_unavailable`	L’accès sandbox n’est pas encore ouvert aux clés de projet.	Attendez l’ouverture de votre accès, sans réessayer en boucle.
`503`	`locality_catalog_unavailable`	Catalogue de localités indisponible.	Réessayez plus tard.
`503`	`locality_catalog_invalid`	Catalogue de localités refusé par ses contrôles d’intégrité.	Réessayez plus tard.
`503`	`locality_catalog_unsearchable`	Le catalogue ne contient aucune localité consultable.	Réessayez plus tard.
`503`	`place_catalog_unavailable`	Catalogue de lieux indisponible.	Réessayez plus tard.
`503`	`place_catalog_invalid`	Catalogue de lieux refusé par ses contrôles d’intégrité.	Réessayez plus tard.

Réessayer sans aggraver

Ne renvoyez jamais une requête refusée en 4xx sans la modifier, sauf après 429.
Après 429, attendez les secondes indiquées par Retry-After.
Après une erreur 5xx, réessayez avec un délai croissant et un nombre limité de tentatives.