# 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.

Fuente: https://fileverity.com/es/docs/idempotency

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

**Solicitud idempotente: cURL**

```bash
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"}'
```

**Solicitud idempotente: JavaScript**

```javascript
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;
}
```

**Solicitud idempotente: Python**

```python
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`, `/analyses` y `/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.

> **Nota.** 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](https://fileverity.com/es/docs/errors.md) y [Límites de frecuencia y encabezados](https://fileverity.com/es/docs/rate-limits.md).