# Errors, pagination & idempotency

> Status codes, the error format, cursor pagination and safe retries for write requests.

Source: https://docs.avenlith.com/en/errors-and-pagination  
Category: API & automation  
Last updated: 2026-09-22

## Status codes

| Code | Meaning |
| --- | --- |
| 200, 201 | Success |
| 202 | Accepted — the action runs asynchronously |
| 400 | Invalid request body or parameters |
| 401 | Missing or invalid token |
| 403 | The token lacks permission |
| 404 | Resource not found |
| 409 | Conflict, e.g. a name already in use |
| 429 | Rate limit exceeded — see `Retry-After` |
| 5xx | Server error — safe to retry with backoff |

## Error format

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

Include the `request_id` when contacting support.

## Pagination

List endpoints return up to 50 items per page (maximum 200). Use the `next_cursor` from `meta` to fetch the next page:

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

## Idempotency

Send an `Idempotency-Key` header with POST requests. Retrying with the same key within 24 hours returns the original response instead of creating a duplicate server.

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