Documentación de la API de Fileverity
Idempotencia
Envíe una Idempotency-Key en las solicitudes POST para que una solicitud reintentada nunca ejecute ni cobre una comprobación dos veces. Comportamiento, respuestas reutilizadas y conflictos.
Un fallo de red puede dejarle sin saber si una solicitud POST llegó. Si simplemente la envía de nuevo, una comprobación podría ejecutarse y cobrarse dos veces. Envíe un encabezado Idempotency-Key y el reintento devolverá la primera respuesta.
Uso del encabezado
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- Envíe cualquier cadena única de 1 a 255 caracteres. Un UUID aleatorio es una buena opción. Use una clave nueva para cada solicitud distinta y reutilice la misma clave solo para reintentar la misma solicitud.
- Funciona en todos los endpoints POST:
/text/detections,/files,/analysesy/analyses/{id}/cancel. - Las claves se limitan a su espacio de trabajo, al modo (live o test) y al endpoint, y se conservan 24 horas. La misma clave usada con una clave Live y con una clave de prueba no entra en conflicto.
Qué obtiene
| Situación | Resultado |
|---|---|
| Primera solicitud con una clave | Se procesa con normalidad. Se guardan las respuestas correctas (estado inferior a 400). |
| Misma clave y mismo cuerpo en un plazo de 24 horas | La respuesta guardada con el mismo estado, más el encabezado idempotent-replayed: true. No se vuelve a ejecutar ni a cobrar nada. |
| Misma clave, cuerpo distinto | 409 idempotency_mismatch. |
| Misma clave mientras la primera solicitud sigue en curso | 409 idempotency_in_progress. Reintente en breve. |
| Misma clave tras una respuesta de error | La clave se libera. Un error no se guarda, así que al reintentar se ejecuta de nuevo la solicitud. |
Una respuesta reutilizada conserva el x-request-id de la nueva solicitud, no el de la original. Las subidas multipart se comparan por sus campos de formulario y el contenido de los archivos.
La idempotencia elimina el trabajo duplicado. No hace que una solicitud fallida tenga éxito: tras service_unavailable o internal_error, espere los segundos de retry-after si la respuesta incluye ese encabezado y reintente después con la misma clave.
Consulte también Errores y Límites de frecuencia y encabezados.