Idempotencia

Las redes fallan. Cuando a un POST se le agota el tiempo, no puedes saber si llegó a la API. Con una Idempotency-Key puedes enviarlo de nuevo sin verificar, crear ni cobrar dos veces.

Cómo funciona

Añade la cabecera a cualquier POST: /verify, /batches y /batches/{batch_id}/cancel.

Shell
curl https://api.salchimail.com/v1/verify \
  -H "Authorization: Bearer $SALCHIMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f" \
  -d '{"email": "ana@example.com", "mode": "mailbox"}'
  • La clave es cualquier cadena única de hasta 255 caracteres. Un UUID es una buena opción.
  • Las claves se guardan 24 horas, por cuenta.
  • Un reintento con la misma clave y el mismo cuerpo devuelve la respuesta guardada, con la cabecera Idempotent-Replayed: true, y no cobra nada.

Conflictos

HTTP code Significado Qué hacer
409 idempotency_key_reused La clave ya se usó con un cuerpo distinto Usa una clave nueva para una petición nueva
409 idempotency_in_progress La primera petición con esa clave sigue en curso Espera y reintenta con la misma clave
JSON
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}

Úsala bien

  • Genera una clave por operación, no por intento: créala antes del primer intento y reutilízala en cada reintento.
  • Guarda la clave junto al trabajo al que pertenece (el registro, la importación) para que un proceso reiniciado reintente con la misma clave.
  • Reintenta ante errores de red, 429, 500 y 503, con la misma clave y una espera creciente. Consulta Límites y errores.
  • No reintentes 400, 401, 402, 403 ni 404 sin cambiar algo: la respuesta será la misma.

La idempotencia importa sobre todo al crear un lote: sin clave, un reintento tras un tiempo de espera agotado puede crear un segundo lote y reservar también sus créditos.

Las peticiones GET se pueden repetir sin riesgo y no necesitan clave.

Ver esta página en Markdown