Documentation de l’API Fileverity
Idempotence
Envoyez un en-tête Idempotency-Key avec les requêtes POST pour qu’une nouvelle tentative ne lance ni ne facture jamais deux fois une vérification. Comportement, réponses rejouées et conflits.
Une panne réseau peut vous laisser sans savoir si une requête POST est bien arrivée. Si vous la renvoyez simplement, une vérification peut être exécutée et facturée deux fois. Envoyez un en-tête Idempotency-Key : la nouvelle tentative renvoie alors la première réponse.
Utiliser l’en-tête
curl https://api.fileverity.com/v1/analyses \ -H "Authorization: Bearer $FILEVERITY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 0e5f6a64-52c2-4b36-9d0d-6f3d2f4c9a10" \ -d '{"model": "fvimg-2", "file": "file_8Hk2pQ4vN9sL1xR7cW3mY6zB"}'async function createAnalysis(body) { const key = crypto.randomUUID(); let lastError; for (let attempt = 0; attempt < 3; attempt++) { try { return await fetch("https://api.fileverity.com/v1/analyses", { method: "POST", headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY, "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify(body), }); } catch (error) { lastError = error; } } throw lastError;}import uuid def create_analysis(body): key = str(uuid.uuid4()) last_error = None for attempt in range(3): try: return requests.post("https://api.fileverity.com/v1/analyses", headers={**headers, "Idempotency-Key": key}, json=body, timeout=90) except requests.ConnectionError as error: last_error = error raise last_error- Envoyez n’importe quelle chaîne unique de 1 à 255 caractères. Un UUID aléatoire est un bon choix. Utilisez une nouvelle clé pour chaque requête distincte, et ne réutilisez la même clé que pour réessayer la même requête.
- L’en-tête fonctionne sur tous les points d’accès POST :
/text/detections,/files,/analyseset/analyses/{id}/cancel. - Les clés sont propres à votre espace de travail, au mode (Live ou Test) et au point d’accès, et conservées 24 heures. La même clé utilisée avec une clé Live et avec une clé de test ne crée pas de conflit.
Ce que vous recevez en retour
| Situation | Résultat |
|---|---|
| Première requête avec une clé | Traitée normalement. Les réponses réussies (statut inférieur à 400) sont enregistrées. |
| Même clé et même corps dans les 24 heures | La réponse enregistrée, avec le même statut, plus l’en-tête idempotent-replayed: true. Rien n’est relancé ni refacturé. |
| Même clé, corps différent | 409 idempotency_mismatch. |
| Même clé alors que la première requête est encore en cours | 409 idempotency_in_progress. Réessayez dans un instant. |
| Même clé après une réponse d’erreur | La clé est libérée. Une erreur n’est pas enregistrée : réessayer relance donc la requête. |
Une réponse rejouée conserve le x-request-id de la nouvelle requête, et non celui de l’originale. Les téléversements multipart sont comparés d’après leurs champs de formulaire et le contenu des fichiers.
L’idempotence évite le travail en double. Elle ne fait pas réussir une requête échouée : après service_unavailable ou internal_error, attendez le nombre de secondes indiqué par retry-after si la réponse contient cet en-tête, puis réessayez avec la même clé.
Voir aussi Erreurs et Limites de débit et en-têtes.