Idempotency

Cómo usar

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - una cadena arbitraria de hasta 64 caracteres, única para cada operación lógica. Recomendado - ULID o UUID v4.

Garantías

• Durante 24 horas después de la primera solicitud con esta clave, las solicitudes repetidas con la misma clave devuelven la misma respuesta sin recálculo y sin deducir créditos.
• Si el cuerpo de la solicitud difiere del original: devuelve 409 Conflict con código idempotency_key_reuse.
• Después de 24 horas la clave se olvida, una nueva solicitud con la misma clave será normal.

Nota

La idempotencia es una protección contra cobros dobles durante fallos de red, no es caché. Para cachear, usa el mecanismo natural X-Cache (5 minutos, véase Créditos y Límites).

Cuándo es necesario

• En manejadores de webhook, donde el reintento viene de un sistema externo (por ejemplo, un proveedor de pagos o CRM envía un evento que tú parseas y haces el cálculo)
• En trabajos en segundo plano, donde el reintento es el comportamiento estándar en fallos
• En pipelines de CI/CD, donde una prueba puede ejecutarse de nuevo

Para interacciones normales “usuario hizo clic en el botón → se mostró el mapa” la idempotencia no es necesaria - el usuario verá el resultado de todos modos, normalmente no hay clics repetidos.

Cuándo no usar

• No pongas clave para ahorrar créditos en solicitudes idénticas: para esto existe X-Cache (gratis, 5 minutos)
• No generes clave desde hash(body): entonces perderás el comportamiento por defecto de Idempotency-Key (repeated 409 en caso de cuerpo diferente)