Notions clés

Idempotence

L’en-tête Idempotency-Key permet de renvoyer une requête POST sans risque : après une coupure réseau ou un délai dépassé, la même requête renvoyée avec la même clé ne crée ni ne débite une seconde génération.

Règle	Valeur
Routes	Toutes les requêtes `POST` de `/v1` : créations et annulation. L’en-tête est ignoré sur les autres méthodes.
Format	De 1 à 255 caractères. Un UUID v4 convient.
Validité	24 heures après la première requête.
Portée	Propre à l’organisation et au mode (test ou réel) de la clé d’API.

Utilisation

Générez une clé d’idempotence par opération, et construisez le corps de la requête une seule fois.
Envoyez la requête avec l’en-tête Idempotency-Key.
Après une coupure ou un délai dépassé, renvoyez exactement la même requête : même méthode, même chemin, même clé et même corps, à l’octet près. Un espace ou un ordre de champs différent suffit à en faire une autre requête.

Réponse à un renvoi

Première requête	Réponse
Réussie	Sa réponse, rejouée telle quelle, avec l’en-tête `idempotent-replayed: true`. Rien n’est exécuté ni débité.
Encore en cours	`409 idempotency_key_in_use` : réessayez plus tard avec la même clé.
Différente de celle-ci (méthode, chemin ou corps)	`409 idempotency_key_reused` : une nouvelle requête exige une nouvelle clé.
Refusée (statut autre que `2xx`)	Le renvoi est traité comme une nouvelle requête.
Acceptée, mais sans réponse reçue (panne ou coupure de notre côté)	La génération créée, dans son état courant (`200` si elle est terminée, `202` si elle est en cours), avec `idempotent-replayed: true`. Rien de plus n’est créé ni débité.

Seule une réponse 2xx est enregistrée : un refus libère la clé. Corrigez la cause (ou, après un 429 ou un 503, attendez le délai indiqué par Retry-After), puis renvoyez la requête avec la même clé.
Une requête de création attend la fin de la génération, en général 1 à 3 minutes. Réglez le délai d’attente de votre client HTTP à 5 minutes : sinon, le renvoi arrive pendant la première requête et reçoit 409 idempotency_key_in_use.
Si la première requête s’est interrompue de notre côté sans répondre, la clé reste réservée 10 minutes au plus (409 idempotency_key_in_use). Passé ce délai, le renvoi rend la génération créée par la première requête, ou est traité comme une nouvelle requête si aucune génération n’a été créée.
Une réponse rejouée reflète l’état de la génération au moment de la première requête : elle peut y être in_progress, et ses output[].url expirent 15 minutes après cette première réponse. Lisez la génération pour obtenir son état à jour.
Un en-tête vide, de plus de 255 caractères ou répété reçoit 400 parameter_invalid, avec param égal à Idempotency-Key.

curl https://api.renderthink.com/v1/renders \
  -H "Authorization: Bearer $RENDERTHINK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d9e-7b4a-4f0e-9c3d-2a8b5e1f7c40" \
  -d '{"image": "https://developers.renderthink.com/assets/scenes/sejour-charpente-export.webp", "quality": "2k"}'