Idempotency

Todos os endpoints da AstroWay API são naturalmente idempotentes: o mesmo input dá sempre o mesmo output, sem efeitos secundários (exceto o débito de créditos e o registo de usage).

Isto significa que um retry após erros de rede é seguro. Mas para que um pedido repetido não debite créditos duas vezes, tens de enviar o header Idempotency-Key.

Como 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 é uma string arbitrária com até 64 caracteres, única para cada operação lógica. Recomendado: ULID ou UUID v4.

Garantias

• Durante 24 horas após o primeiro pedido com esta chave, os pedidos repetidos com a mesma chave devolvem a mesma response sem novo cálculo e sem débito de créditos.
• Se o body do pedido for diferente do original, é devolvido 409 Conflict com o código idempotency_key_reuse.
• Passadas 24 horas, a chave é esquecida e um novo pedido com a mesma chave é tratado como um pedido normal.

Nota

Idempotency é uma proteção contra o débito duplo em falhas de rede, não uma cache. Para cache, usa o mecanismo natural X-Cache (5 minutos, vê Créditos e limites).

Quando é necessário

• Em webhook handlers, onde o retry vem de um sistema externo (por exemplo, um fornecedor de pagamentos ou um CRM envia um evento que tu processas e usas para fazer um cálculo)
• Em jobs em segundo plano, onde o retry é o comportamento normal em caso de falha
• Em pipelines de CI/CD, onde um teste pode ser executado novamente

Para interações comuns do tipo “o utilizador clicou no botão → mostrámos o mapa”, a idempotência não é necessária: o utilizador vê o resultado de qualquer forma e normalmente não há cliques repetidos.

Quando não usar

• Não definas a chave para poupar créditos em pedidos idênticos: para isso existe o X-Cache (gratuito, 5 minutos)
• Não geres a chave a partir de hash(body): assim perdes o comportamento padrão do Idempotency-Key (o 409 repetido quando o body é diferente)