Idempotência
Como o cabeçalho `Idempotency-Key` evita cobrança dupla em retries sobre redes instáveis.
Por que importa
Redes falham no meio da requisição. Se você faz POST /v1/activations e a conexão cai antes de ver a resposta, não sabe se a ativação foi criada. Retry ingênuo pode cobrar duas vezes.
O cabeçalho Idempotency-Key resolve isso: envie a mesma chave no retry, receba o mesmo resultado.
Como usar
Gere um UUID por operação lógica, envie-o em cada retry da mesma operação:
KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
-H "Authorization: Bearer $EVESES_API_KEY" \
-H "Idempotency-Key: $KEY" \
-d '{"country":"ua", "service":"telegram"}'
Repetir a mesma chamada com o mesmo Idempotency-Key retorna a resposta original — sem segunda ativação, sem segunda cobrança.
TTL
Chaves são lembradas por 24 horas. Depois disso o slot é liberado e a mesma chave pode ser reutilizada como nova.
Onde aplica
Todos os endpoints POST /v1/* que criam ou cobram: ativações, aluguéis, depósitos, extensões. Endpoints de leitura (GET) já são idempotentes e ignoram o cabeçalho.
Conflitos
Se você reutiliza a mesma chave com um body diferente, a API retorna 409 idempotency_conflict. Mantenha o body idêntico nos retries ou gere uma nova chave.
Comportamento do SDK
SDKs oficiais auto-geram chaves de idempotência para cada chamada de criação e as reutilizam em retries automáticos. Você pode sobrescrever com uma chave explícita se precisar.