> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quentli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotencia

> Evita operaciones duplicadas al reintentar solicitudes de escritura a la API de Quentli.

La idempotencia ayuda a diseñar APIs que sean resistentes a fallas de red y tiempos de espera. Sin idempotencia, reintentar una operación de que crea recursos o modifica datos puede crear clientes, facturas o pagos duplicados.

Para evitarlo, envía un `X-Idempotency-Key` único en cada operación lógica que use `POST`, `PUT`, `PATCH` o `DELETE`.

## Cómo usar

Genera una clave antes de enviar la solicitud y guárdala junto con el trabajo pendiente en tu sistema. Reutiliza exactamente la misma clave si necesitas reintentar esa operación. Recomendamos usar un UUID; la clave debe tener entre 1 y 200 caracteres.

```bash theme={null}
curl --request POST https://api.quentli.com/v1/invoices \
  --header 'Authorization: Bearer <tu_api_key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: 36e08a7e-a63d-4ab3-a533-efb5d4221eaa' \
  --data '{
    "input": {
      "customerId": "cus_1234567890",
      "items": [
        {
          "concept": {
            "displayName": "Mensualidad",
            "amount": 25000,
            "currency": "MXN"
          },
          "quantity": 1
        }
      ]
    }
  }'
```

Si tu cliente agota el tiempo de espera o pierde la respuesta, repite la misma solicitud con la misma clave.

## Qué considera la misma solicitud

Una clave se asocia con el método HTTP, la ruta, los parámetros de consulta y el cuerpo de la solicitud. El primer uso de la clave fija esa combinación.

* Repite la misma operación con la misma clave, ruta, parámetros y cuerpo.
* Usa una clave nueva para otra factura, pago o cambio de datos.
* No reutilices una clave con un cuerpo, parámetros o ruta distintos. Quentli devuelve `409 Conflict` para evitar una operación ambigua.

## Respuestas y reintentos

Quentli conserva por 24 horas la respuesta de una solicitud idempotente que termina entre `200` y `499`. Un reintento idéntico devuelve el mismo código y cuerpo, junto con el encabezado:

```text theme={null}
X-From-Cache: true
```

Quentli reserva la clave durante 60 segundos mientras procesa la primera solicitud. Si un reintento llega en ese periodo, devuelve `409 Conflict`. Espera y vuelve a intentar con la misma clave y la misma solicitud.

Las respuestas `4xx` también se conservan. Si corriges la solicitud después de un error de validación o autorización, crea una clave nueva para la solicitud corregida.

<Warning>
  Las respuestas `5xx` no se conservan. Después de un error de servidor, el resultado de la operación puede ser
  indeterminado. Consulta el estado del recurso o contacta a soporte antes de repetir una operación que pudiera haber
  creado un cobro o una factura.
</Warning>