生产 API
轮询、重试和幂等
安全重试,遵守 Retry-After,在 energy_usable 变为 true 时立即发起交易,并仅在两个结束标志都为 true 时停止轮询。
本页内容
Rentron 不发送 webhook 或 callback。GET /v1/energy/orders/{id} 是获取订单状态的唯一可信依据。
建议的轮询方式
创建后,在 1、2、5 秒后轮询 Location,之后每 10 秒轮询一次。并行追踪多笔订单时请加入少量随机抖动。
一旦 energy_usable 变为 true,就可以发起您自己的交易:此时 Energy 已分配到该地址。之后请继续轮询,只有 lifecycle_final === true 和 delivery_final === true 时才停止。
重试矩阵
| 结果 | 处理方式 |
|---|---|
| 网络错误 / GET 超时 | 使用退避重试。 |
| 订单 POST 超时 | 重放完全相同的请求体和 client_request_id。 |
429 |
等待 Retry-After 指定的秒数。 |
GET 返回 500 / 503 |
使用退避和随机抖动重试。 |
400、413、415 |
修正请求;自动重试无效。 |
401 |
修正凭证、签名、时间戳或 IP 允许列表。 |
409 幂等冲突 |
停止并检查被重复使用的客户端 ID。 |
三个信号:一个用来行动,两个用来停止
用来行动的是 energy_usable。它在 available 状态下就变为 true,比 delivered 早约一分钟,表示 Energy 已分配到该地址并且可以使用。等待 delivered 只会白白消耗您已经付费的租赁时长。
用来停止的是 delivery_final 和 lifecycle_final。delivery_final 结束资源分配尝试,在 available 状态下仍为 false,因为分配结果尚未经过独立验证。lifecycle_final 结束整个租赁时长:分配成功后,订单会持续有效,直到 rental_finished。按 energy_usable、按单个标志或按单个状态停止,都会过早结束轮询。
频率限制
公开时间、已验证流量和创建订单分别应用限制。不要猜测限制数值;429 和 Retry-After 是接口合约的一部分。
Rentron