Concepts clés

Idempotence

Réessaie une requête qui modifie des données sans l'exécuter deux fois. Envoie une Idempotency-Key, et Gemlead renvoie le premier résultat à chaque nouvel essai.

Envoyer une clé

Ajoute le header Idempotency-Key à n'importe quel POST, PATCH, PUT ou DELETE. Utilise une valeur propre à l'opération, de 255 caractères au plus. Un UUID v4 fait très bien l'affaire.

Si la connexion est coupée avant que tu reçoives la réponse, renvoie la même requête avec la même clé. Gemlead fait le travail une seule fois et te donne son résultat, donc un endpoint webhook n'est jamais créé deux fois.

Les clés sont conservées 24 heures. Les requêtes GET ne modifient jamais rien et n'ont pas besoin de clé.

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4f5e-3b0a-4f7e-9d2c-6a8b1e2d4c7f" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot"]
  }'

Comment Gemlead répond

Requête	Réponse
Même clé, même méthode, même chemin et même corps, sous 24 heures	La première réponse, avec le même statut et le même corps, et le header `Idempotent-Replayed: true`.
Même clé, autre méthode, chemin ou corps	409 `idempotency_error` avec le code `idempotency_key_reused`.
Même clé pendant que la première requête tourne encore	409 avec le code `idempotency_key_in_use`. Réessaie une seconde plus tard.
Une clé de plus de 255 caractères	400 avec le code `idempotency_key_invalid`.

Quand réessayer

Une erreur réseau ou un timeout, réessaie avec la même clé.
Un 500, réessaie avec la même clé après une courte attente.
Un 400, 401, 403 ou 404, corrige la requête et envoie-la avec une nouvelle clé.