Guides

Erreurs

Toute erreur a la même forme : un code stable, un message lisible en français et l’identifiant de la requête.

La forme d’une erreur

Le corps d’une réponse en erreur est { "error": { "code", "message", "request_id", "details"? } } :

code : stable, c’est lui que votre code doit tester ;
message : explication en français, à journaliser ou à montrer, mais dont le texte peut changer ;
request_id : identifiant de la requête, aussi dans l’en-tête X-Request-Id de toute réponse, erreur ou non ;
details : présent pour certaines erreurs seulement (champs invalides, droit exigé).

Journalisez X-Request-Id avec vos erreurs et citez-le si vous nous écrivez (contact@regroupe-immo.fr) : il nous permet de retrouver la requête.

Code	Cause	Que faire
`validation_error`	Paramètre invalide, manquant ou incohérent : aucun secteur ou deux, cercle incomplet, identifiant mal formé… `details` liste les champs en cause (`path`, `message`).	Corrigez la requête ; ne la renvoyez pas telle quelle.
`bad_request`	Requête refusée au traitement (valeurs incohérentes).	Corrigez la requête.
`invalid_cursor`	Curseur illisible, obtenu avec un autre tri ou sur un autre point d’entrée.	Renvoyez le `next_cursor` reçu, tel quel, avec le même `sort`.
`since_too_old`	`since` remonte à plus de 30 jours.	Importez le secteur, puis suivez le flux à partir de sa tête.
`api_key_in_url`	Clé passée dans l’adresse.	Passez-la dans l’en-tête `Authorization`, et remplacez-la : elle a pu être journalisée.

Ces réponses portent l’en-tête WWW-Authenticate: Bearer realm="regroupe-immo".

Code	Cause	Que faire
`missing_api_key`	Aucune clé dans la requête.	Ajoutez l’en-tête `Authorization: Bearer ri_live_…`.
`invalid_api_key`	Clé mal formée ou inconnue.	Vérifiez la copie de la clé. Des échecs répétés mettent votre adresse IP à l’écart.
`revoked_api_key`	Clé révoquée.	Utilisez une clé active.
`expired_api_key`	Clé expirée.	Créez une nouvelle clé.

Code	Cause	Que faire
`insufficient_scope`	La clé n’a pas le droit exigé, donné dans `details.required_scope`.	Utilisez une clé qui porte ce droit, s’il est ouvert à votre compte.
`api_access_disabled`	L’accès à l’API est coupé pour votre compte.	Écrivez-nous en citant le `request_id`.
`account_disabled`	Votre compte est désactivé.	Écrivez-nous en citant le `request_id`.
`account_blocked`	Votre compte est bloqué.	Écrivez-nous en citant le `request_id`.
`ip_blocked`	L’adresse IP d’où part la requête est bloquée.	Écrivez-nous en citant le `request_id`.

Code	Cause	Que faire
`not_found`	Point d’entrée inconnu, ou bien introuvable : identifiant inconnu, ou bien pas encore diffusé pour votre plan.	Vérifiez l’adresse et l’identifiant. Un bien récent peut apparaître après le délai de diffusion.
`not_valued`	Le bien n’a pas encore été valorisé (audit complet).	Réessayez plus tard.

Code	Cause	Que faire
`cursor_expired`	Curseur du flux des changements de plus de 30 jours.	Réimportez le secteur, puis reprenez le flux à partir de sa tête.

Ces réponses portent l’en-tête Retry-After et jamais de details.

Code	Cause	Que faire
`rate_limited`	Débit de la minute, ou plafond par seconde, atteint.	Attendez Retry-After secondes.
`quota_exceeded`	Quota du jour atteint.	Arrêtez-vous : le quota repart à minuit, heure de Paris.
`too_many_concurrent_requests`	Déjà 4 requêtes en cours pour votre compte.	Attendez la fin d’une requête ; limitez le parallélisme.
`too_many_auth_failures`	Trop de clés invalides présentées depuis votre adresse IP.	Corrigez la clé, puis attendez Retry-After secondes.

Code	Cause	Que faire
`internal_error`	Erreur de notre côté.	Réessayez plus tard ; si l’erreur persiste, écrivez-nous en citant le `request_id`.

Cette réponse porte l’en-tête Retry-After: 5.

Code	Cause	Que faire
`query_timeout`	Le temps de calcul de la requête a dépassé sa limite.	Réessayez une fois ; si l’erreur se répète, réduisez le secteur ou ajoutez des filtres.

Testez error.code, jamais le texte du message.
Ne renvoyez pas telle quelle une requête refusée en 400, 401 ou 403 : elle sera refusée de nouveau.
Réessayez après un 429 ou un 503 en respectant Retry-After (sauf quota_exceeded), et après un 500 en espaçant les essais. Voir Limites et quotas.