Claves de idempotencia

Las redes fallan. Si una petición agota el tiempo de espera, no puedes saber si el correo fue aceptado. Envía un encabezado Idempotency-Key y reintenta sin miedo: la misma clave con el mismo cuerpo devuelve la respuesta original y envía el correo una sola vez.

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send(
  { from: "Acme <hello@acme.com>", to: "user@example.com", subject: "Receipt", html: "<p>Thanks</p>" },
  { idempotencyKey: "receipt-order-1042" },
);

console.log(error ?? data);

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" \
  -H "Idempotency-Key: receipt-order-1042" \
  -H "Content-Type: application/json" \
  -d '{ "from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>" }'

requests.post(
    "https://api.spacepost.dev/emails",
    headers={
        "Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}",
        "Idempotency-Key": "receipt-order-1042",
    },
    json={"from": "Acme <hello@acme.com>", "to": ["user@example.com"], "subject": "Receipt", "html": "<p>Thanks</p>"},
)

Reglas

Compatible con POST /emails y POST /emails/batch.
La clave tiene de 1 a 256 caracteres.
Las claves están limitadas a tu equipo y se recuerdan durante 24 horas.
Misma clave y mismo cuerpo de petición: se devuelve la respuesta guardada (mismo estado, mismo cuerpo) y no se envía nada nuevo.
Misma clave y un cuerpo distinto: 409 invalid_idempotent_request.
Misma clave mientras la primera petición sigue en curso: 409 concurrent_idempotent_requests. Espera un momento y reintenta.
Una clave fuera del rango de 1 a 256 caracteres: 400 invalid_idempotency_key.
Las peticiones que fallan no se guardan, así que puedes corregir el problema y reutilizar la clave.

“Mismo cuerpo” significa que el JSON analizado es idéntico. Cambiar cualquier campo, incluido scheduled_at: "in 1 hour" (que se evalúa en el momento de la petición), cuenta como una petición distinta.

Cómo elegir las claves

Deriva la clave del evento de negocio, no de un valor aleatorio generado en el momento del reintento:

Bien	Mal
`receipt-order-1042`	`crypto.randomUUID()` en cada intento
`welcome-user-u_1042`	`Date.now()`
`digest-2026-w43-chunk-3`	La misma constante para todos los correos