Помилки

Кожна відповідь із помилкою має однакову оболонку:


{
  "error": "human-readable message",
  "code": "machine_readable_code",
  "request_id": "req_a1b2c3"
}

error призначено для логів і людей; code - це те, на чому має базуватися логіка вашого клієнта. request_id має те саме значення, що повертається в заголовку відповіді X-Request-ID - вказуйте його під час створення тікета підтримки.

Коди статусів

Статус	Клас	Повторити?
`400 Bad Request`	Валідація / некоректний JSON	Ні - виправте запит
`401 Unauthorized`	Відсутні або недійсні облікові дані	Ні - авторизуйтесь повторно
`403 Forbidden`	Автентифіковано, але доступ заборонено	Ні
`404 Not Found`	Ресурс не існує або ви не маєте доступу до нього	Ні
`409 Conflict`	Слаг зайнятий, невідповідність idempotency-key, колізія станів	Ні (виправити) або так (оновити стан і спробувати знову)
`422 Unprocessable Entity`	Схема валідна, але семантично неправильно	Ні
`429 Too Many Requests`	Обмеження частоти запитів - дивіться заголовок `Retry-After`	Так після паузи (backoff)
`500 Internal Server Error`	Помилка сервера - вкажіть `request_id`	Так із паузою (backoff)
`502 / 503 / 504`	Тимчасові збої інфраструктури	Так з експоненціальною паузою (backoff)

Поширені коди помилок

Код	Значення
`validation_failed`	Одне або кілька полів не пройшли валідацію схеми
`slug_taken`	Запитуваний персоналізований слаг уже використовується
`link_destination_unsafe`	Цільова URL-адреса позначена url-scanner як небезпечна
`quota_exceeded`	Робоча область досягла м’якого або жорсткого ліміту на посилання або кліки
`domain_not_verified`	DNS кастомного домену ще не розповсюдився
`idempotency_key_mismatch`	Той самий ключ, інше корисне навантаження - змініть щось одне
`audit_immutable`	Спроба змінити вже підписаний BAA

Ідемпотентність

Ендпоінти, що змінюють дані, приймають заголовок Idempotency-Key. Той самий ключ + те саме тіло протягом 24 годин повертає оригінальну відповідь (відтворену з кешу). Той самий ключ + інше тіло повертає 409 idempotency_key_mismatch.


curl -X POST https://api.elido.app/v1/links \
  -H "Authorization: Bearer $ELIDO_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "destination_url": "https://example.com" }'

Повторні спроби

Повторюйте лише помилки 429, 5xx та помилки мережі. Використовуйте експоненціальну паузу (backoff) із джитером (наприклад, min(60s, 2^attempt + random(0, 1000ms))). Для помилок 429 віддавайте перевагу значенню Retry-After, якщо воно присутнє.

Офіційні SDK реалізують це автоматично.