Idempotencia

Los fallos de red, timeouts y caídas de proceso son inevitables. Aeses soporta claves de idempotencia para que reintentar un POST sea seguro — la misma solicitud lógica solo tiene efecto una vez, sin importar cuántas veces la reintentes.

Enviar una clave de idempotencia

Añade el header Idempotency-Key a cualquier POST. El valor puede ser cualquier string de hasta 255 caracteres; un UUID v4 es un buen valor por defecto.

curl https://api.aeses.io/v1/deposits \
-H "x-api-key: sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
  "asset": "USDT",
  "chain": "ethereum"
}'

La primera respuesta se almacena durante 24 horas. Las solicitudes posteriores con la misma clave y el mismo cuerpo devuelven la respuesta original — incluido el status code original — sin ejecutar la operación de nuevo.

Dónde usarla

Recomendamos firmemente enviar una clave de idempotencia en cada POST. En la práctica es obligatoria para:

• POST /v1/deposits — evita generar múltiples direcciones en reintentos.
• POST /v1/withdrawals — previene gasto doble si tu cliente reintenta.
• POST /v1/charges — evita crear payment intents duplicados.
• POST /v1/webhook-deliveries/:id/replay — el reenvío es naturalmente idempotente, pero la clave previene floods accidentales.

GET y DELETE son naturalmente idempotentes y no requieren clave.

Generar claves

Genera una clave una vez por operación lógica, antes del primer intento. Persístela junto a la operación en tu base de datos y reutilízala en cada reintento hasta que la operación tenga éxito. Patrón habitual:

operation_id = uuid4()
save(state="pending", idempotency_key=operation_id)

while not done:
  try:
    response = api.create_deposit(..., idempotency_key=operation_id)
    save(state="confirmed", deposit_id=response.id)
    done = True
  except RetryableError:
    sleep(backoff())

Nunca generes una clave nueva dentro del bucle de reintentos — anula el propósito.

Comportamiento del replay

La respuesta replicada es idéntica byte a byte a la original, incluidas las respuestas de error. Si la solicitud original devolvió 400 invalid_request_error, se replica el mismo 400; ningún estado de negocio cambia.

El Request-Id original se preserva en los replays para auditoría. La respuesta HTTP además incluye:

• Idempotency-Replayed: true — presente cuando la respuesta proviene del caché.

Conflictos

Si reutilizas la misma clave con un cuerpo de solicitud distinto, Aeses devuelve 409 idempotency_key_reused:

{
"error": {
  "type": "idempotency_error",
  "code": "idempotency_key_reused",
  "message": "Idempotency-Key already used with a different request payload.",
  "request_id": "req_01HXYZ..."
}
}

Esto suele indicar un bug en el cliente: la clave se reutilizó para una operación no relacionada. Genera una clave nueva para cada nueva operación lógica.

TTL

Los registros de idempotencia caducan 24 horas tras la solicitud original. Después, la misma clave puede reutilizarse para una operación nueva sin conflicto. Si reintentas tras la ventana de 24h, la solicitud se procesa como nueva — diseña tus reintentos para completarse bastante dentro de esa ventana.