Коды ошибок
Все ошибки возвращают { ok: false, error: { code, message, field?, meta?, request_id } } с соответствующим HTTP-статусом, никогда с 200. Таблица содержит все коды каналов /v1 и встраивания и синхронизируется с серверными реестрами.
Структура ответа с ошибкой
http
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Request-Id: 018f2b00-0000-7000-8000-0000000000ff
{
"ok": false,
"error": {
"code": "wallet.insufficient_balance",
"message": "Số dư ví không đủ để thực hiện giao dịch.",
"field": null,
"meta": null,
"request_id": "018f2b00-0000-7000-8000-0000000000ff"
}
}Почему domain.reason вместо числовых кодов 0000
Стандартный HTTP: прокси, мониторинг и REST-клиенты уже обрабатывают HTTP-статусы, поэтому стандартные статусы работают с существующей инфраструктурой.
Понятное имя: wallet.insufficient_balance понятен без поиска по таблице; новые коды не нарушают существующую обработку.
Старая система ожидает числа? Строковый код неизменяем и служит постоянным ключом для ваших внутренних таблиц перевода.
4 правила обработки ошибок
Сначала проверяйте HTTP-статус, затем код
HTTP-статус определяет обработку на уровне транспорта (повтор, оповещение, размыкание цепи); error.code — сообщение пользователю. Статусы стабильнее конкретных кодов.
Неизвестные коды не должны прерывать работу
Новые функции добавляют коды ошибок. Неизвестный код обрабатывайте по HTTP-статусу, записывайте исходный код и request_id, показывайте общее сообщение. Не допускайте необработанных исключений.
Всегда сохраняйте request_id
Каждый ответ содержит X-Request-Id; ответ с ошибкой повторяет его в теле. Этот идентификатор позволяет поддержке найти журнал конкретного запроса.
Учитывайте Retry-After для 429 и 503
Читайте Retry-After вместо фиксированной задержки. При 429 заголовки X-RateLimit-Limit / Remaining / Reset помогают снизить частоту до блокировки.
Таблица соответствия кода и HTTP
Сгруппировано по доменам. Справочник API также указывает возможные ошибки каждого метода — сверяйтесь с ним.
Показано 91 / 91 кодов
Аутентификация, ключи и лимиты partner.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
partner.invalid_key | 401 | Недействительный ключ API. | Нет: повтор без изменений снова завершится ошибкой |
partner.invalid_signature | 401 | Неверная подпись запроса. | Нет: повтор без изменений снова завершится ошибкой |
partner.timestamp_expired | 401 | Время запроса слишком сильно отличается от времени сервера. | Нет: повтор без изменений снова завершится ошибкой |
partner.nonce_reused | 401 | Этот nonce уже использован. | Нет: повтор без изменений снова завершится ошибкой |
partner.ip_not_allowed | 403 | IP-адрес отсутствует в списке разрешённых. | Нет: повтор без изменений снова завершится ошибкой |
partner.scope_denied | 403 | Ключ API не имеет прав на вызов этого эндпоинта. | Нет: повтор без изменений снова завершится ошибкой |
partner.key_suspended | 403 | Ключ API приостановлен. | Нет: повтор без изменений снова завершится ошибкой |
partner.key_revoked | 403 | Ключ API отозван. | Нет: повтор без изменений снова завершится ошибкой |
partner.endpoint_disabled | 503 | Эта группа эндпоинтов временно отключена. | Да: повторите без изменений |
partner.rate_limited | 429 | Превышен лимит запросов. Повторите позже. | Да: повторите без изменений |
partner.package_not_visible | 404 | Этот код тарифа недоступен для покупки с вашим ключом. | Нет: повтор без изменений снова завершится ошибкой |
partner.daily_quota_exceeded | 429 | Дневная квота запросов исчерпана. Повторите завтра. | Да: повторите без изменений |
partner.wrong_host | 403 | Ключ не соответствует серверу. Используйте `https://api-testing.tongkhoesim.com` для `tke_test_` и `https://api.tongkhoesim.com` для `tke_live_`. | Нет: повтор без изменений снова завершится ошибкой |
Общие ошибки API internal.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
internal.validation_failed | 400 | Переданные данные недействительны. | Нет: повтор без изменений снова завершится ошибкой |
internal.invalid_filter | 400 | Недопустимое условие фильтра. | Нет: повтор без изменений снова завершится ошибкой |
internal.invalid_sort_field | 400 | Недопустимое поле сортировки. | Нет: повтор без изменений снова завершится ошибкой |
internal.unauthenticated | 401 | Войдите снова: сессия отсутствует или истекла. | Нет: повтор без изменений снова завершится ошибкой |
internal.forbidden | 403 | У вас нет прав на это действие. | Нет: повтор без изменений снова завершится ошибкой |
internal.not_found | 404 | Запрошенный ресурс не найден. | Нет: повтор без изменений снова завершится ошибкой |
internal.route_not_found | 404 | Этот путь не существует. Проверьте метод и путь в документации. | Нет: повтор без изменений снова завершится ошибкой |
internal.method_not_allowed | 405 | Этот метод HTTP не поддерживается. | Нет: повтор без изменений снова завершится ошибкой |
internal.conflict | 409 | Конфликт состояния не позволяет выполнить действие. | Нет: повтор без изменений снова завершится ошибкой |
internal.unsupported_media_type | 415 | Этот тип содержимого не поддерживается. | Нет: повтор без изменений снова завершится ошибкой |
internal.rate_limited | 429 | Слишком много запросов. Повторите позже. | Да: повторите без изменений |
internal.server_error | 500 | Произошла системная ошибка. Повторите позже. | Да: повторите без изменений |
internal.service_unavailable | 503 | Сервис временно недоступен. Повторите позже. | Да: повторите без изменений |
internal.limit_exceeded | 422 | Достигнут допустимый лимит. Удалите лишние элементы и повторите. | Нет: повтор без изменений снова завершится ошибкой |
internal.money_frozen | 503 | Финансовые операции приостановлены для проверки учётного журнала. Повторите позже. | Да: повторите без изменений |
Каталог тарифов catalog.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
catalog.cursor_mismatch | 400 | Курсор не соответствует текущим фильтрам. Начните с первой страницы без параметра cursor. | Нет: повтор без изменений снова завершится ошибкой |
Расчёты и заказы order.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
order.quote_not_found | 404 | Предложение не найдено. | Нет: повтор без изменений снова завершится ошибкой |
order.quote_expired | 409 | Срок действия предложения истёк. Создайте новое. | Нет: повтор без изменений снова завершится ошибкой |
order.quote_already_committed | 409 | Это предложение уже преобразовано в заказ. | Нет: повтор без изменений снова завершится ошибкой |
order.package_not_allowed | 400 | Тариф не существует или недоступен для покупки. | Нет: повтор без изменений снова завершится ошибкой |
order.not_deliverable | 409 | Заказ ещё не завершён; действие недоступно. | Нет: повтор без изменений снова завершится ошибкой |
order.quantity_limit_exceeded | 400 | Количество eSIM превышает лимит на заказ. | Нет: повтор без изменений снова завершится ошибкой |
order.fulfillment_config_changed | 409 | Настройки выдачи тарифа изменились. Создайте новое предложение. | Нет: повтор без изменений снова завершится ошибкой |
order.refund_suggestion_pending | 409 | Для заказа ожидает одобрения предложение возврата. Сначала обработайте его. | Нет: повтор без изменений снова завершится ошибкой |
eSIM esim.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
esim.out_of_stock | 409 | Недостаточно запасов этого тарифа. | Нет: повтор без изменений снова завершится ошибкой |
esim.not_cancellable | 409 | Текущее состояние eSIM не позволяет отменить её. | Нет: повтор без изменений снова завершится ошибкой |
esim.lpa_not_available | 409 | У eSIM ещё нет кода LPA (не активирована или не зарегистрирована). | Нет: повтор без изменений снова завершится ошибкой |
esim.not_eligible | 409 | Эта eSIM не подходит для пополнения. | Нет: повтор без изменений снова завершится ошибкой |
esim.not_activated | 409 | eSIM не установлена. Установите и активируйте её перед пополнением. | Нет: повтор без изменений снова завершится ошибкой |
esim.topup_not_supported | 409 | Тариф не поддерживает пополнение. | Нет: повтор без изменений снова завершится ошибкой |
esim.topup_provider_mismatch | 409 | Этот тариф пополнения принадлежит другому поставщику. Выберите тариф для этой eSIM. | Нет: повтор без изменений снова завершится ошибкой |
esim.refund_not_eligible | 409 | Для этой eSIM недоступен запрос возврата. | Нет: повтор без изменений снова завершится ошибкой |
esim.refund_request_pending | 409 | Для eSIM уже ожидает запрос возврата. | Нет: повтор без изменений снова завершится ошибкой |
esim.suspended | 409 | eSIM приостановлена. Возобновите её перед выполнением действия. | Нет: повтор без изменений снова завершится ошибкой |
Кошелёк wallet.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
wallet.frozen | 409 | Кошелёк заморожен; платежи недоступны. | Нет: повтор без изменений снова завершится ошибкой |
wallet.velocity_hold | 409 | Кошелёк заблокирован для проверки. Обратитесь в поддержку. | Нет: повтор без изменений снова завершится ошибкой |
wallet.insufficient_balance | 402 | Недостаточно средств в кошельке для этой операции. | Нет: повтор без изменений снова завершится ошибкой |
wallet.deleted | 409 | Кошелёк получателя недействителен (удалён). | Нет: повтор без изменений снова завершится ошибкой |
wallet.velocity_exceeded | 429 | Превышен порог операций за короткое время. Кошелёк заблокирован для проверки. | Нет: повтор без изменений снова завершится ошибкой |
Запросы возврата refund.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
refund.note_required | 400 | Укажите причину отказа в возврате. | Нет: повтор без изменений снова завершится ошибкой |
Цены продажи pricing.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
pricing.no_price_for_buyer | 409 | Для вас ещё не задана цена этого тарифа. | Нет: повтор без изменений снова завершится ошибкой |
Поставщик eSIM provider.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
provider.disabled | 409 | Поставщик тарифа отключён; продажа невозможна. | Нет: повтор без изменений снова завершится ошибкой |
provider.api_group_disabled | 409 | Эта группа услуг поставщика отключена. | Нет: повтор без изменений снова завершится ошибкой |
provider.not_registered | 500 | Для поставщика не настроен коннектор. | Да: повторите без изменений |
provider.unsupported | 400 | Поставщик не поддерживает это действие. | Нет: повтор без изменений снова завершится ошибкой |
provider.timeout | 504 | Истекло время ожидания ответа поставщика. Повторите позже. | Да: повторите без изменений |
provider.auth_failed | 502 | Не удалось пройти аутентификацию у поставщика. | Да: повторите без изменений |
provider.rate_limited | 429 | Поставщик ограничивает запросы. Повторите позже. | Да: повторите без изменений |
provider.malformed_response | 502 | Поставщик вернул некорректные данные. | Да: повторите без изменений |
provider.call_failed | 502 | Ошибка вызова поставщика. | Да: повторите без изменений |
provider.out_of_stock | 409 | Тариф отсутствует в запасах поставщика. | Нет: повтор без изменений снова завершится ошибкой |
provider.msisdn_taken | 409 | Этот MSISDN уже назначен другому абоненту у поставщика. | Нет: повтор без изменений снова завершится ошибкой |
provider.msisdn_exhausted | 409 | У поставщика не осталось доступных MSISDN. | Нет: повтор без изменений снова завершится ошибкой |
Idempotency idempotency.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
idempotency.conflict | 409 | Этот Idempotency-Key уже использован с другим содержимым. | Нет: повтор без изменений снова завершится ошибкой |
Возможности поставщика capability.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
capability.not_supported | 422 | Тариф не поддерживает запрошенную функцию. | Нет: повтор без изменений снова завершится ошибкой |
Тестовый режим и симуляция testmode.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
testmode.live_key_forbidden | 403 | Этот эндпоинт требует тестовый ключ (`tke_test_`) на api-testing. Используйте тестовый ключ той же организации. | Нет: повтор без изменений снова завершится ошибкой |
testmode.not_test_item | 422 | Это реальная eSIM; тестовый режим обрабатывает только тестовые eSIM. Для отмены реального заказа запросите возврат. | Нет: повтор без изменений снова завершится ошибкой |
testmode.invalid_scenario | 422 | Недопустимый сценарий. Передайте хотя бы одно поле: `data_used_mb`, `status`, `expire_now`, `throttled`; `status` допускает только released|installed|enabled|disabled. | Нет: повтор без изменений снова завершится ошибкой |
testmode.no_sellable_package | 422 | Нет доступного тарифа с ценой для создания примеров данных. Нужен хотя бы один продаваемый тариф с ценой. | Нет: повтор без изменений снова завершится ошибкой |
Webhook webhook.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
webhook.health_check_failed | 422 | URL вебхука не прошёл проверку доступности. | Нет: повтор без изменений снова завершится ошибкой |
webhook.url_not_allowed | 422 | URL вебхука не разрешён. Требуется общедоступный адрес с https. | Нет: повтор без изменений снова завершится ошибкой |
webhook.not_configured | 404 | Для ключа API не настроен вебхук. | Нет: повтор без изменений снова завершится ошибкой |
webhook.delivery_not_found | 404 | Доставка вебхука не найдена. | Нет: повтор без изменений снова завершится ошибкой |
webhook.already_configured | 409 | Для ключа API уже есть вебхук (один на ключ). Измените его через `PUT /v1/webhooks/{id}` или удалите через `DELETE /v1/webhooks/{id}` перед созданием нового. | Нет: повтор без изменений снова завершится ошибкой |
webhook.not_found | 404 | Эндпоинт вебхука не принадлежит вызывающему ключу API. | Нет: повтор без изменений снова завершится ошибкой |
Состояние организации org.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
org.invoice_profile_incomplete | 422 | Профиль организации для выставления счетов неполон (название, налоговый номер, адрес). | Нет: повтор без изменений снова завершится ошибкой |
org.suspended | 403 | Организация приостановлена. | Нет: повтор без изменений снова завершится ошибкой |
org.closed | 403 | Организация закрыта. | Нет: повтор без изменений снова завершится ошибкой |
Публичное встраивание embed.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
embed.invalid_token | 401 | Недействительный токен встраивания. | Нет: повтор без изменений снова завершится ошибкой |
embed.token_revoked | 410 | Канал встраивания больше не активен. | Нет: повтор без изменений снова завершится ошибкой |
embed.rate_limited | 429 | Слишком частые запросы канала встраивания. Повторите позже. | Да: повторите без изменений |
embed.package_not_visible | 404 | Тариф не найден. | Нет: повтор без изменений снова завершится ошибкой |
Счета с НДС invoice.*
| code | HTTP | Значение | Можно повторить? |
|---|---|---|---|
invoice.order_not_settled | 409 | Заказ ещё не рассчитан: выполняется возврат. Повторите выставление счёта через несколько минут. | Да: повторите без изменений |
invoice.profile_incomplete | 422 | Профиль организации для выставления счетов неполон. Заполните его. | Нет: повтор без изменений снова завершится ошибкой |
invoice.already_requested | 409 | Для этого заказа уже есть счёт. | Нет: повтор без изменений снова завершится ошибкой |
invoice.nothing_to_invoice | 409 | После вычета возвратов сумма к выставлению отсутствует. | Нет: повтор без изменений снова завершится ошибкой |
invoice.amount_changed | 409 | Возврат только что изменил сумму заказа. Проверьте её и повторите выставление счёта. | Да: повторите без изменений |
invoice.buyer_invalid | 422 | Данные компании-получателя неполны или налоговый номер недействителен. | Нет: повтор без изменений снова завершится ошибкой |