Ошибки¶

Публичный API возвращает стандартные HTTP-коды. Текущие два эндпоинта (POST /verifications/, GET /verifications/{id}/) сохраняют исходные форматы тел ответов (legacy-формат DRF) для обратной совместимости — новые эндпоинты будут использовать единый envelope (см. ниже).

Каталог HTTP-кодов¶

Код	Значение	Когда
`400 Bad Request`	Валидация запроса	Невалидный JSON, отсутствуют обязательные поля, плохой формат `phone` или `webhook_url`.
`401 Unauthorized`	Аутентификация	Нет заголовка, неверный / отозванный токен.
`403 Forbidden`	Авторизация	Аутентификация прошла, но не Bearer (например, сессия).
`404 Not Found`	Ресурс не найден	Несуществующий `verification_id` или принадлежит другой компании.
`405 Method Not Allowed`	Неверный метод	Например, PUT на `/verifications/`.
`429 Too Many Requests`	Лимит	Превышен 120 req/min на ключ. Заголовок `Retry-After`.
`500 Internal Server Error`	Бага на нашей стороне	Сообщите в саппорт с `verification_id` и временем.
`503 Service Unavailable`	Сервис занят	Все активные SIP-линии заняты текущими верификациями. Заголовок `Retry-After: 60`.

Форматы тел ответа¶

Валидация (400)¶

DRF-формат: ключ — имя поля, значение — массив строк-ошибок.

{
  "phone": ["Некорректный номер телефона"]
}

Возможные ошибки полей:

Поле	Сообщения
`phone`	`Некорректный номер телефона` — единое нормализованное сообщение (детали парсера не раскрываются, чтобы нельзя было энумерировать валидные форматы).
`webhook_url`	`Введите корректный URL.` (невалидный синтаксис); `webhook_url scheme must be http or https, got '<scheme>'`; `webhook_url must not contain embedded credentials`; `webhook_url resolves to a private/internal address (<ip>)`; `webhook_url host cannot be resolved: …`
`client_ref`	`Убедитесь, что это значение содержит не более 120 символов.`
`ttl_seconds`	`Убедитесь, что это значение больше либо равно 1.`; `Убедитесь, что это значение меньше либо равно 3600.`

Язык сообщений

Стандартные сообщения DRF (валидация полей, URL) локализованы на русский. Сообщения SSRF-гарда webhook_url приходят на английском — они генерируются отдельным валидатором (см. Безопасность).

Если в теле битый JSON — вернётся 400 с {"detail": "<сообщение о разборе JSON>"}.

Аутентификация (401)¶

{
  "detail": "Недействительный API-ключ"
}

Конкретный текст зависит от причины (нет заголовка, неверный формат, неизвестный ключ, отозванный ключ) — полный список в Аутентификации. В заголовках: WWW-Authenticate: Bearer.

Авторизация (403)¶

{
  "detail": "Требуется API-ключ."
}

Возникает, если запрос прошёл другую аутентификацию (не Bearer API-ключ) — публичные эндпоинты требуют именно ключ API.

Не найдено (404)¶

{
  "detail": "Не найдено."
}

Лимит (429)¶

{
  "detail": "Запрос был отклонён. Ожидается доступность через 23 сек."
}

В заголовках: Retry-After: 23. Подробнее — Лимиты.

Сервис занят (503)¶

Возникает, когда на момент запроса все активные и зарегистрированные SIP-линии заняты другими, ещё не завершёнными верификациями. Это ожидаемая ситуация при пиковой нагрузке, а не инцидент: запрос не ставится в очередь, ответ приходит сразу.

{
  "error": "no_dial_number_available",
  "message": "Сервис временно занят, все линии заняты. Попробуйте позже.",
  "retry_after": 60
}

В заголовках: Retry-After: 60. Это единственный legacy-эндпоинт с машинно-читаемым error-кодом. Рекомендуется ловить именно этот HTTP-код (503) и/или строку "no_dial_number_available"; поле message предназначено для человекочитаемого вывода и может меняться в будущих версиях, не завязывайте на него логику.

Свободная линия появится автоматически, как только одна из текущих верификаций завершится звонком или истечёт по TTL (по умолчанию до 5 минут). Каждое событие исчерпания пула логируется на стороне сервера на уровне WARNING — оператор видит частоту и при устойчивом росте расширяет пул линий.

Новый envelope (для будущих эндпоинтов)¶

При добавлении новых эндпоинтов мы будем использовать единый формат:

{
  "error": {
    "code": "<machine_code>",
    "message": "<human-readable>",
    "fields": {
      "<field>": ["<msg>", "..."]
    }
  }
}

Поле fields — опциональное (только для ошибок валидации).

Машинно-читаемые коды¶

`code`	HTTP	Описание
`invalid_request`	400	Ошибка валидации
`authentication_failed`	401	Аутентификация
`permission_denied`	403	Авторизация
`not_found`	404	Не найдено
`method_not_allowed`	405	Метод не разрешён
`conflict`	409	Конфликт состояния
`rate_limited`	429	Превышен лимит
`no_dial_number_available`	503	Нет свободных DID
`idempotency_conflict`	409	Idempotency-ключ переиспользован с другим телом
`service_unavailable`	503	Временно недоступно
`internal_error`	500	Внутренняя ошибка

Существующие два эндпоинта продолжают использовать legacy-формат. Документация конкретного эндпоинта точно указывает, какой формат возвращается.