# Ошибки, пагинация и идемпотентность

> Коды ответа, формат ошибок, курсорная пагинация и безопасные повторы запросов на запись.

Source: https://docs.avenlith.com/ru/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). Для следующей страницы используйте `next_cursor` из `meta`:

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

## Идемпотентность

Передавайте заголовок `Idempotency-Key` в POST-запросах. Повтор с тем же ключом в течение 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"}'
```