错误、分页与幂等性

状态码、错误格式、游标分页以及写请求的安全重试。

参考1 分钟阅读更新于 2026年9月22日.md

本页内容

状态码
错误格式
分页
幂等性

状态码#

状态码	含义
200、201	成功
202	已接受——操作异步执行
400	请求体或参数无效
401	缺少令牌或令牌无效
403	令牌权限不足
404	资源不存在
409	冲突，例如名称已被占用
429	超出速率限制——参见 `Retry-After`
5xx	服务器错误——可退避重试

错误格式#

JSON

{
  "error": {
    "code": "invalid_region",
    "message": "Region 'ist2' does not exist.",
    "request_id": "req_7Hn2kQ"
  }
}

联系技术支持时请附上 request_id。

分页#

列表接口每页最多返回 50 条（上限 200）。使用 meta 中的 next_cursor 获取下一页：

Shell

curl "https://api.avenlith.com/v1/servers?per_page=50&cursor=eyJpZCI6InNydl84ZjJrMSJ9" \
  -H "Authorization: Bearer $AVENLITH_TOKEN"

幂等性#

POST 请求请携带 Idempotency-Key 头。24 小时内使用相同键重试将返回原始响应，而不会重复创建服务器。

Shell

curl -X POST https://api.avenlith.com/v1/servers \
  -H "Authorization: Bearer $AVENLITH_TOKEN" \
  -H "Idempotency-Key: 5c1f7e8a-8a0b-4e8e-9d1b-1f0f7a2b9c11" \
  -d '{"name": "web-01", "plan": "vps-pro", "region": "ist1"}'

本页内容对您有帮助吗？

仍需帮助？

我们的工程师 7×24 小时处理工单——平均首次响应时间 7 分钟。

联系技术支持