Idempotencia

Reintenta una solicitud y habrás enviado el mismo correo dos veces. Deja que un formulario de checkout se envíe dos veces y el cliente recibe dos recibos. La solución es el encabezado Idempotency-Key, que garantiza que una solicitud se ejecuta como máximo una vez.

Cuando Bitelio ve una clave por primera vez, la solicitud sigue su curso normal. Cuando la misma clave vuelve a aparecer dentro de tu proyecto, la solicitud es rechazada con un 409 en lugar de ejecutarse una segunda vez.

El encabezado es compatible en ambos endpoints de escritura de la API pública:

• POST /v1/track
• POST /v1/send

Enviar una clave

Cualquier cadena de 1 a 255 caracteres ASCII imprimibles funciona como clave. Lo que importa es que cada operación lógica tenga la suya propia — ya sea un UUID, o algo que derives de tus propios registros, como receipt-order-1234.

curl -X POST https://api.bitelio.com/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Idempotency-Key: receipt-order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Your receipt",
    "body": "<p>Thanks for your order!</p>"
  }'

await fetch('https://api.bitelio.com/v1/send', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_your_secret_key',
    'Idempotency-Key': 'receipt-order-1234',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject: 'Your receipt',
    body: '<p>Thanks for your order!</p>',
  }),
});

import requests

requests.post(
    "https://api.bitelio.com/v1/send",
    headers={
        "Authorization": "Bearer sk_your_secret_key",
        "Idempotency-Key": "receipt-order-1234",
    },
    json={
        "to": "customer@example.com",
        "subject": "Your receipt",
        "body": "<p>Thanks for your order!</p>",
    },
)

Qué ocurre en una reutilización

Una clave repetida vuelve como un 409 con el código de error IDEMPOTENCY_KEY_REUSED. Dentro de details encontrarás información sobre la solicitud que reclamó la clave primero:

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "Idempotency-Key \"receipt-order-1234\" has already been used",
    "statusCode": 409,
    "details": {
      "key": "receipt-order-1234",
      "originalRequest": "POST /v1/send",
      "originalRequestAt": "2025-01-15T10:30:00.000Z",
      "originalStatusCode": 200
    }
  }
}

Si originalStatusCode es null, la primera solicitud aún no ha terminado — ambas solicitudes con la misma clave llegaron simultáneamente y esta perdió la carrera.

Qué fallos liberan la clave

Una solicitud fallida no siempre consume la clave.

Si un 5xx consumió una clave pero tienes la certeza de que la operación nunca tuvo efecto, reintenta con una clave nueva.

Alcance y expiración

Una clave pertenece a tu proyecto en su conjunto, no a un único endpoint — una vez gastada en /v1/track, no puede reproducirse contra /v1/send. Proyectos separados, en cambio, pueden usar cada uno la misma cadena de clave sin interferir entre sí.

Las claves reclamadas expiran después de 24 horas y pueden volver a usarse a partir de ese momento.

Múltiples destinatarios

Cuando pasas un arreglo de destinatarios a POST /v1/send, se procesan secuencialmente — pero la clave de idempotencia protege la solicitud como una unidad, no destinatario por destinatario. Si la solicitud muere a mitad de camino con un 5xx, algunos destinatarios pueden ya haber recibido su correo; la clave permanece reclamada exactamente por esa razón, así que un reintento ingenuo no puede alcanzarlos dos veces.

Si necesitas control a nivel de destinatario, emite una solicitud por destinatario, cada una con su propia clave.