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` du quota d’abonnement	Attendez la durée indiquée par `Retry-After` avant la prochaine requête.
`429` de `POST /public/v1/issues`	Lisez le Problem Details, vérifiez `code: rate_limited`, puis respectez `Retry-After` avant de reprendre.
`503` du limiteur de quota d’abonnement	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, les erreurs applicatives par défaut et le 429 de POST /public/v1/issues utilisent des Problem Details. Ce 429 contient code: rate_limited. 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. Le 429 du quota d’abonnement reste un corps application/json { "message": "Too Many Requests" }. Attendez Retry-After avant de reprendre ; cette représentation ne s’applique pas à POST /public/v1/issues.

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

Les en-têtes RateLimit-* décrivent les trois fenêtres — seconde, minute et jour — du quota d’abonnement. Leurs valeurs dépendent de votre abonnement : lisez la réponse plutôt que de coder des valeurs d’exemple en dur. Ils ne décrivent pas le limiteur de POST /public/v1/issues. Cet endpoint utilise des compteurs de signalement indépendants ; la limite par seconde et par minute suit le forfait d’accès aux données courant, tandis que la limite quotidienne est plafonnée à 2 500.

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.

Les réponses 201 et 429 de POST /public/v1/issues n’utilisent pas ces tableaux. Elles renvoient X-RateLimit-Limit et X-RateLimit-Remaining ; le 429 ajoute Retry-After et X-RateLimit-Reset.

En-tête	Comportement	Action du client
`X-RateLimit-Limit`	Indique le maximum appliqué par le limiteur de signalement.	Lisez cette valeur à chaque réponse ; elle dépend du forfait courant.
`X-RateLimit-Remaining`	Indique la capacité restante du limiteur de signalement.	Ralentissez avant d’épuiser cette capacité.
`Retry-After`	Indique le délai à respecter après un `429` ; il accompagne aussi un `503` du limiteur de quota.	N’envoyez aucune nouvelle requête avant la fin de ce délai.
`X-RateLimit-Reset`	Indique la réinitialisation fournie par le limiteur après un `429` de signalement.	Utilisez-le avec `Retry-After` pour planifier la reprise.
`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 de quota d’abonnement 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é