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.
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 |
{
"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,500y503, con la misma clave y una espera creciente. Consulta Límites y errores. - No reintentes
400,401,402,403ni404sin 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.