# 错误、分页与幂等性

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

Source: https://docs.avenlith.com/zh/errors-and-pagination  
Category: API 与自动化  
Last updated: 2026-09-22

## 状态码

| 状态码 | 含义 |
| --- | --- |
| 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` 获取下一页：

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

## 幂等性

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

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