Fiabilité de l’API : erreurs et limites

Traitez chaque réponse d’erreur selon son code de statut, son type de contenu et les identifiants de diagnostic disponibles. Ne traitez jamais une réponse en erreur comme un résultat réussi.

Traitez la réponse

Résultat	Action
`2xx`	Traitez le corps de réponse documenté.
`400`	Lisez la réponse Problem Details, corrigez la syntaxe ou les paramètres de la requête, puis envoyez une nouvelle requête corrigée.
`401`	Vérifiez le token et l’en-tête `Authorization: Bearer <token>`. Ne réessayez qu’après les avoir corrigés.
`403`	Vérifiez les droits et les data access de l’intégration, puis corrigez la configuration avant de réessayer.
`409`	Lisez la réponse de configuration JSON, ouvrez `configurationUrl` ou le dashboard pour configurer les data access, puis renvoyez la requête.
`404`	Vérifiez l’identifiant ou l’URL recherchée. Ne réessayez pas la même requête sans changement.
`422`	Lisez les détails de validation, corrigez les données de requête, puis renvoyez la requête.
`429`	Attendez la durée indiquée par `Retry-After` avant la prochaine requête.
`503` du limiteur	Attendez le délai indiqué par `Retry-After`, puis réessayez.
Autres `5xx` transitoires ou erreur réseau	Utilisez un backoff avec un nombre de réessais borné. Journalisez les trace IDs disponibles.

Distinguez les corps de réponse et les diagnostics

Les erreurs 400, 401, 422 et les erreurs applicatives par défaut utilisent des Problem Details. Le corps contient traceId ; lorsqu’il est émis par Immoteur, l’en-tête X-Trace-Id porte le même identifiant de corrélation. Conservez les identifiants disponibles avec le code de statut, l’endpoint et l’heure de la requête. Ne supposez pas qu’une réponse 403 ou 404 contient ce corps ou ces en-têtes. La réponse 409 est un corps application/json de configuration qui contient message, configurationUrl et documentationUrl ; elle ne promet pas de trace ID. Suivez configurationUrl ou ouvrez API → Accès aux données dans le dashboard, puis envoyez une nouvelle requête. La réponse 429 est également différente : son type de contenu est application/json et son corps est { "message": "Too Many Requests" }. Attendez Retry-After avant de reprendre.

Lisez les en-têtes de limite et de diagnostic

Les valeurs de limite sont ordonnées par seconde, minute, puis jour. Elles dépendent de votre abonnement : lisez la réponse plutôt que de coder des valeurs d’exemple en dur.

En-tête	Comportement	Action du client
`RateLimit-Policy`	Décrit la politique de rate limit.	Utilisez-le pour interpréter les autres en-têtes de limite.
`RateLimit-Limit`	Indique la limite applicable.	Adaptez le débit à la valeur reçue, sans coder une limite en dur.
`RateLimit-Remaining`	Indique la capacité restante.	Ralentissez avant d’épuiser cette capacité.
`RateLimit-Reset`	Indique quand la capacité se renouvelle.	Utilisez-le pour planifier la reprise.
`Retry-After`	Indique le délai à respecter après une réponse limitée ou une indisponibilité du limiteur.	N’envoyez aucune nouvelle requête avant la fin de ce délai.
`X-Trace-Id`	Identifiant de trace associé aux Problem Details lorsqu’Immoteur l’émet.	Conservez-le avec le contexte de la requête lors de l’analyse.

Reprenez les échecs temporaires en sécurité

Une indisponibilité 503 du limiteur utilise application/json avec { "message": "Rate limit service unavailable" } et un délai Retry-After. Respectez ce délai avant de réessayer ; la réponse d’indisponibilité actuellement observée indique une seconde. Pour les autres réponses 5xx transitoires ou les erreurs réseau, utilisez un backoff avec un nombre de réessais borné. Journalisez les trace IDs disponibles, le code de statut et le contexte de la requête pour analyser un échec persistant. Ne réessayez pas 400, 401, 403, 409, 404 ou 422 avant d’avoir appliqué la correction indiquée plus haut. Utilisez curl --include pendant l’intégration pour consulter les en-têtes et le corps de réponse :

curl --include --show-error --silent \
  'https://api.immoteur.com/public/v1/auth' \
  -H "Authorization: Bearer $IMMOTEUR_TOKEN"

Pour les tokens et les data access, consultez Tokens API et accès aux données. Pour les erreurs propres à un endpoint, utilisez la référence API générée.

Démarrer

API

Webhooks

Référence OpenAPI

Fiabilité de l’API : erreurs et limites

Traitez la réponse

Distinguez les corps de réponse et les diagnostics

Lisez les en-têtes de limite et de diagnostic

Reprenez les échecs temporaires en sécurité

​Traitez la réponse

​Distinguez les corps de réponse et les diagnostics

​Lisez les en-têtes de limite et de diagnostic

​Reprenez les échecs temporaires en sécurité

Traitez la réponse

Distinguez les corps de réponse et les diagnostics

Lisez les en-têtes de limite et de diagnostic

Reprenez les échecs temporaires en sécurité