Saltar al contenido principal

Idempotencia

La API soporta idempotencia para reintentar solicitudes de forma segura, sin ejecutar la misma operación dos veces. Útil cuando una llamada se interrumpe en tránsito y no recibes respuesta — por ejemplo, una solicitud para crear una cuenta por pagar que falla por un error de red puede reintentarse con la misma clave, garantizando que solo se cree un registro.

Cómo usarlo​

Envía el encabezado X-Idempotency-Key: <clave> en cualquier solicitud POST, PUT o PATCH. La clave es libre, generada por tu lado. Recomendamos UUID v4 u otra cadena aleatoria con entropía suficiente para evitar colisiones.

curl -i \
  -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: 8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21' \
  -H 'User-Agent: Mi Sistema (contacto@example.com)' \
  -d '{
    "account_id": "00000000-0000-0000-0000-000000000001",
    "description": "Aluguel Janeiro/2026",
    "amount": "3500.00",
    "due_date": "2026-01-10"
  }' \
  -X POST 'https://api.finance.kobana.com.br/v1/payables'

Cómo funciona​

Cuando el servidor recibe una solicitud con X-Idempotency-Key:

  1. Reserva la clave de forma atómica, en el ámbito del workspace. Dos workspaces distintos pueden usar la misma clave sin conflicto.
  2. Calcula la huella de la solicitud — SHA-256 de método + ruta + cuerpo en bruto. Ese hash se almacena junto a la clave.
  3. Ejecuta el handler. Si devuelve una respuesta, el servidor registra status_code, cuerpo y encabezados relevantes vinculados a la clave.
  4. Marca la clave como completada. Cualquier nueva solicitud con la misma clave dentro de 24 horas recibe la respuesta original verbatim — mismo status_code, mismo cuerpo, mismos encabezados — más el encabezado X-Idempotency-Replayed: true para indicar que se trata de una reejecución.
aviso

La capa guarda el resultado independientemente de si fue éxito o fracaso. Los reintentos con la misma clave devuelven el mismo resultado, incluyendo errores 5xx — para volver a intentarlo de verdad después de un error del servidor, genera una clave nueva.

Límites​

  • Longitud máxima de la clave: 255 caracteres.
  • Retención: las claves expiran automáticamente 24 horas después de su creación.
  • Ámbito: por workspace. Una clave usada en un workspace no interfiere con otro.
  • Caracteres aceptados: cualquier cadena UTF-8 imprimible.

Conflictos​

Si la misma clave se reutiliza con una solicitud diferente (cualquier cambio en método, ruta o cuerpo), la API responde 409 conflict con details.reason = "idempotency_key_reused".

{
  "error": {
    "code": "conflict",
    "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key.",
    "details": { "reason": "idempotency_key_reused" }
  }
}

Métodos aceptados​

Método¿Acepta X-Idempotency-Key?
POST✅ Sí
PATCH✅ Sí
GET❌ No (ya es idempotente por definición)
DELETE❌ No (ya es idempotente por definición)

Buenas prácticas​

  • Una clave por operación lógica. No reutilices la misma clave para crear dos recursos diferentes — recibirás 409 conflict.
  • Persiste la clave junto con el estado de la operación en tu lado, para que el reintento tras un crash o reinicio use la misma clave.
  • Combínalo con backoff exponencial al recibir 5xx o timeout.
  • Descarta la clave después de 24 horas. No hay ganancia en mantenerla en tu lado después de ese plazo.