Коды ошибок

При ошибке проверьте HTTP статус и поле message.

Тело ошибки

Бизнес-ошибки всегда возвращают машиночитаемый code для программной обработки. Некорректные параметры (валидация) и несуществующие маршруты возвращают стандартный формат Laravel: { “message”: ”…”, “errors”: { … } }. Проверяйте входные данные до отправки.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

Ошибка

`code`	HTTP	Описание
`unauthorized`	401	API-ключ отсутствует, неверен или деактивирован.
`account_banned`	403	Аккаунт заблокирован. Обратитесь в поддержку.
`invalid_realtime_request`	400	Некорректный realtime-запрос (например, номер без международного префикса +, если country не указан).
`idempotency_key_required`	400	Realtime-запросы требуют заголовок Idempotency-Key.
`invalid_idempotency_key`	422	Недопустимый Idempotency-Key: 1-128 символов из букв, цифр и . _ : -
`idempotency_conflict`	409	Тот же Idempotency-Key использован с другим содержимым запроса.
`request_in_progress`	409	Идентичный realtime-запрос ещё обрабатывается. Повторите чуть позже (Retry-After: 1).
`empty_input`	422	Загруженный файл не содержит пригодных строк.
`product_not_found`	422	Указанный slug продукта не существует или неактивен.
`product_mode_not_supported`	422	Этот эндпоинт не принимает такой режим продукта (realtime-продукты не для массовых эндпоинтов).
`invalid_country`	422	Продукт не поддерживает указанную страну.
`too_few_numbers`	422	Отправка ниже минимума продукта.
`too_many_numbers`	422	Отправка превышает максимум платформы.
`insufficient_balance`	402	Недостаточно средств. Пополните баланс и повторите.
`realtime_disabled`	403	Realtime-проверка не включена для этого аккаунта.
`realtime_rate_limited`	429	Превышен лимит realtime-запросов. Соблюдайте retry_after.
`product_pricing_unavailable`	503	Цены для этого продукта ещё не настроены. Обратитесь в поддержку.
`detection_capacity_unavailable`	503	Сейчас нет доступной ёмкости для проверки. Повторите позже.
`realtime_route_unavailable`	503	Нет доступного realtime-маршрута. Повторите позже.
`realtime_fact_cache_unavailable`	503	Зависимость realtime временно недоступна. Повторите позже.
`realtime_rate_limiter_unavailable`	503	Лимитер временно недоступен. Повторите позже.
`internal_error`	500	Внутренняя ошибка сервера. Повтор с тем же Idempotency-Key безопасен.

Ошибки без кода

Не у каждого сбоя есть code. Эндпоинты задач сообщают о четырёх условиях только статусом HTTP и message, потому что эти сбои возникают раньше, чем срабатывает путь бизнес-ошибок:

HTTP	Условие	Тело
`404`	`task_id` не существует или принадлежит другому аккаунту	только `message`
`404`	`GET /v1/tasks/{token}/download` — файл результата недоступен, истёк или больше не подлежит скачиванию	только `message`
`422`	`GET /v1/tasks/{token}/result` — результат не готов: задача не завершена, файл не сформирован или истёк	только `message`
`422`	Параметры запроса не прошли валидацию	`{ "message": …, "errors": { … } }`

В этих случаях ориентируйтесь на статус HTTP. message — для логов и для человека, разбирающего инцидент, а не для логики.

Повторные попытки

Правильная реакция на ошибку зависит от того, может ли повторный запрос дать другой результат.

Сначала нужно действие

Повтор без изменений воспроизведёт ту же ошибку.

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

Подождать и повторить

Временная ошибка — тот же запрос должен пройти позже.

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

Результат неизвестен

Запрос мог примениться, а мог и нет. Повторите с тем же ключом.

internal_error