Idempotence

Il arrive que le réseau coupe une requête sans que vous sachiez si elle est arrivée. Pour relancer un POST sans exécuter (ni payer) le travail deux fois, envoyez un en-tête Idempotency-Key - une valeur unique par opération logique. Un UUID convient parfaitement.

curl -X POST https://developers.grem.capital/api/v1/valuation/express \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c8a90-1e2b-4c77-9a10-2b6d0f9e4a11" \
  -d '{"propertyCategory":"apartment","addressText":"Torstraße 12, Berlin","totalArea":64}'

Fonctionnement

• La première requête avec une clé s'exécute normalement ; sa réponse réussie est enregistrée.
• Une nouvelle tentative avec la même clé renvoie la réponse enregistrée : l'outil n'est pas relancé et n'est pas facturé une seconde fois.
• Tant que la première requête est en cours, une deuxième requête avec la même clé reçoit 409 avec title: idempotency_conflict. Patientez et réessayez avec la même clé.
• Si la première requête a échoué, la clé est libérée - une nouvelle tentative avec elle s'exécute à nouveau. Une requête qui n'a jamais atteint le service (connexion refusée) libère également la clé.
• Après un délai dépassé (502 provider_error) d'un outil, d'une création d'annonce ou d'une création de lead, la clé reste réservée pendant 15 minutes, afin qu'une nouvelle tentative ne puisse pas exécuter le travail deux fois. Vérifiez le résultat avant de répéter : GET /works pour les outils, GET /objects et GET /leads pour les créations. Les résultats de l'amélioration de photos, des sites et des brouillons ne sont pas conservés dans GET /works - vérifiez-les dans l'espace personnel ou parmi vos annonces. Une répétition après ces 15 minutes exécute à nouveau le travail (et sa facturation).
• L'évaluation express fait exception : après un délai dépassé, la clé est libérée - répétez-la immédiatement avec la même clé, une évaluation terminée est renvoyée gratuitement : ni l'évaluation ni l'appel d'API ne sont facturés à nouveau.
• 524 signifie que le réseau situé devant l'API a coupé une réponse qui n'avait pas commencé dans les ~100 secondes ; le travail continue. Après 524 et 504, la clé n'est pas libérée : répétez avec la même clé - le résultat terminé est renvoyé sans seconde facturation, et tant que le premier appel est en cours, vous recevez 409. Lancez plutôt les évaluations express et de loyer avec Prefer: respond-async : la tâche est renvoyée immédiatement.
• Un plan d'étage ou une vérification de rapport lancés avec Prefer: respond-async peuvent se terminer en failed avec code: interrupted (un redémarrage du service a interrompu la tâche). Rien n'est facturé et la clé est libérée : renvoyez la même requête avec la même clé - les fichiers sont envoyés à nouveau, sans seconde facturation. Le SDK le fait automatiquement.
• Une clé est mémorisée pendant 24 heures et est liée à votre clé d'API et à l'opération - la méthode plus le chemin réel : des valeurs identiques sous des clés d'API différentes, la même clé sur un autre outil, ou POST /objects/property et POST /objects/rental sont des requêtes différentes.

Où elle s'applique

Dans le SDK, la clé est le dernier argument d'une méthode.

Voir aussi

• Erreurs - quoi relancer et quand.
• Limites et facturation - ce qui est facturé.