Erreurs
Une erreur a toujours la même forme : un statut HTTP, un code stable à tester dans votre programme et un message lisible, en français.
Mis à jour le 10 novembre 2026
Format
{
"error": {
"code": "not_found",
"status": 404,
"message": "Candidat inconnu : jean-dupont. Liste : /api/v1/candidats",
"docs": "https://isoloir2027.fr/donnees-ouvertes/api/erreurs#not_found"
}
}Testez error.code, pas le message : le code ne change pas, le texte peut être reformulé. error.status reprend le statut HTTP (il figurait seul dans les premières réponses d'erreur, et il est gardé pour elles), error.docs renvoie au paragraphe de cette page qui décrit le code. Les en-têtes de limite de débit sont présents sur les erreurs comme sur les réponses réussies, sauf quand la requête est refusée avant d'être comptée (clé dans l'adresse, clé invalide, adresse inconnue).
Les codes
bad_requestCause. Un paramètre a une valeur inattendue : une date qui n'est pas au format AAAA-MM-JJ, une limite hors de 1 à 200, un réseau inconnu, un horodatage illisible.
Que faire. Le message nomme le paramètre et la forme attendue. Corrigez la requête ; la répéter telle quelle donnera la même erreur.
key_in_urlCause. Une clé a été passée dans l'adresse (api_key, apikey, key ou cle).
Que faire. Envoyez-la dans l'en-tête Authorization: Bearer ou X-Api-Key, puis régénérez-la : elle a pu être enregistrée dans des journaux.
invalid_api_keyCause. La clé envoyée n'existe pas ou a été révoquée.
Que faire. Vérifiez la variable d'environnement qui la contient (espaces, guillemets, clé tronquée). Une clé perdue se régénère depuis le tableau de bord.
api_key_requiredCause. Appel sans clé après la fin de l'accès sans clé (en-tête Sunset).
Que faire. Créez une clé gratuite et envoyez-la à chaque requête.
plan_insufficientCause. Réservé à une fonction qui demanderait une offre supérieure. Aucun point d'accès de la version 1 ne le renvoie aujourd'hui.
Que faire. Le message dirait quelle offre est nécessaire.
not_foundCause. L'adresse n'existe pas sous /api/v1/, ou le candidat demandé (candidat=) n'est pas suivi.
Que faire. La liste des points d'accès est à /api/v1, celle des candidats à /api/v1/candidats.
goneCause. Le point d'accès a été retiré pour de bon et ne reviendra pas.
Que faire. Retirez-le de votre code ; le message indique les points d'accès qui restent. La page des changements date chaque retrait.
rate_limitedCause. La limite de votre offre (ou de l'accès sans clé) est atteinte pour la fenêtre en cours.
Que faire. Attendez la durée de Retry-After en secondes. Voir les limites de débit pour réduire le nombre d'appels.
internal_errorCause. Une erreur imprévue côté serveur.
Que faire. Réessayez quelques minutes plus tard. Si elle persiste, écrivez à contact@isoloir2027.fr avec l'adresse appelée et l'heure.
Erreurs et CSV
Avec ?format=csv, une erreur reste une réponse JSON avec son statut HTTP : vérifiez le statut avant d'écrire le fichier, sans quoi votre tableur recevrait le message d'erreur à la place des données.