Помилки

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

Код	Значення	Може списатися
200	Успіх. Списання може дорівнювати 0.	✅ Так
400	Bad request. Також повертається при нестачі балансу.	❌ Ні
401	Немає або невалідний Api-Key.	❌ Ні
404	Ресурс не знайдено.	❌ Ні
422	Помилка валідації запиту.	❌ Ні
429	Перевищено хвилинний ліміт або ліміт одночасних запитів.	❌ Ні
500	Внутрішня помилка сервісу.	❌ Ні
503	Сервіс тимчасово недоступний.	❌ Ні

Формат помилки

Документовані помилки API, крім помилок валідації, повертають поле detail з рядком:

{ "detail": "Опис помилки" }

Помилки валідації (422) повертають структуру у стилі FastAPI:

{
  "detail": [
    {
      "loc": ["query", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

• loc — шлях до збитого поля.
• msg — людино-читаване повідомлення.
• type — програмний тип помилки.

Приклади

401 — відсутній або невалідний токен

{ "detail": "Not authenticated" }

400 — недостатньо балансу

{ "detail": "Not enough balance to perform this action. Please top up your balance." }

При нестачі балансу на платному ендпоінті відповідь також містить Telesint-Billing-Charged: 0, Telesint-Billing-Balance і Cache-Control: private, no-store. Для інших відповідей 400, 404, 422, 500 і 503 billing-заголовки не гарантуються.

404 — ресурс не знайдено

{ "detail": "User not found" }

429 — перевищено рейтліміт

{ "detail": "Rate limit exceeded", "reason": "rpm" }

Відповідь містить Retry-After. Значення reason — rpm або concurrency; докладніше на сторінці Рейтліміти.

503 — лімітер недоступний

{ "detail": "Rate limiter is temporarily unavailable" }

Ця відповідь містить Retry-After: 5 і не тарифікується.

Стратегія ретраїв

Статус	Ретраїти?
2xx	—
400, 401, 404, 422	Ні. Полагодити запит / токен / баланс, потім повторити.
429	Так. Зачекати кількість секунд із Retry-After.
5xx	Так. Враховувати Retry-After, якщо він є; інакше backoff: 1с, 2с, 4с, 8с.