Ошибки

Коды статусов

Код	Значение	Может списаться
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с.