幂等性

为什么重要

网络会在请求中途失败。如果你 POST /v1/activations 而连接在你看到响应前断开，你不知道激活是否已创建。简单地重试可能会扣两次费。

Idempotency-Key 头部解决了这个问题：在重试时发送相同的密钥，得到相同的结果。

如何使用

为每个逻辑操作生成一个 UUID，并在同一操作的每次重试时发送它：

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"}'

使用相同的 Idempotency-Key 重新执行相同调用会返回原始响应——没有第二次激活，没有第二次扣费。

TTL

密钥被记住 24 小时。之后槽位被释放，同一密钥可作为新密钥重用。

在哪些地方适用

所有创建或扣费的 POST /v1/* 端点：激活、租用、存款、延期。读取端点（GET）已经幂等并忽略此头部。

冲突

如果你用相同密钥但不同 body 重用，API 返回 409 idempotency_conflict。在重试时保持 body 相同，或生成新密钥。

SDK 行为

官方 SDK 为每次创建调用自动生成幂等性密钥，并在自动重试时重用。如有需要可用显式密钥覆盖。