Справочник ошибок

Ошибки и Rate Limits

Полный справочник кодов ошибок, маппинга HTTP, политик rate limit и стратегий retry.

HTTP-коды статусов

Современный REST API использует стандартные HTTP-коды. Тело ответа включает структурированный объект ошибки.

КодСтатусЗначение
400Bad RequestВалидация запроса не пройдена (отсутствуют или некорректны параметры)
400Bad RequestНеверный формат сайта для email (код EMAIL_SITE_INVALID): относится к созданию email-активации и повторному заказу. Ранее в этом случае возвращался 500.
401UnauthorizedТребуется авторизация или ключ API неверен
402Payment RequiredНедостаточно средств в кошельке для выполнения
403ForbiddenАвторизован, но нет прав на этот ресурс
404Not FoundРесурс не найден (например, ID активации не существует)
409ConflictЗапрос конфликтует с текущим состоянием
422Unprocessable EntityЗапрос корректен по форме, но семантически невалиден
422Unprocessable EntityСайт для email не поддерживается (код EMAIL_SITE_NOT_SUPPORTED): относится к созданию email-активации и повторному заказу. Ранее в этом случае возвращался 500.
429Too Many RequestsПревышен rate limit: см. заголовок Retry-After
429Too Many RequestsЛимит одновременных активаций: JSON-код ACTIVATION_CONCURRENCY_LIMIT (поля limit, open). Подождите, затем повторите попытку.
429Too Many RequestsЛимит защиты от злоупотреблений (error "Too Many Requests"; с 2026-10-20 в JSON-теле также есть код ANTI_ABUSE_THROTTLE). Временно применяется, если аккаунт за недавний период запросил много номеров, отменил почти все и не получил ни одного кода. Используйте имеющиеся номера или подождите, затем повторите попытку.
500Internal Server ErrorНеожиданная ошибка сервера: retry с экспоненциальной задержкой
502Bad GatewayСбой на стороне вышестоящего провайдера. Сообщение в теле обычно имеет вид "Upstream error: <CODE>" (для заказов eSIM "Upstream eSIM error: <CODE>"). С 2026-10-20 <CODE> один из кодов ниже; до этой даты это может быть необработанный код.
503Service UnavailableUpstream-провайдер недоступен: retry позже

Коды ошибок вышестоящего провайдера (HTTP 502)

Сообщение 502 обычно имеет вид "Upstream error: <CODE>"; для заказов eSIM используется "Upstream eSIM error: <CODE>". С 2026-10-20 <CODE> это один из наших собственных кодов, а не строка провайдера, а заказы eSIM возвращают только UPSTREAM_BUSY, UPSTREAM_REFUSED, UPSTREAM_INVALID_REQUEST или UPSTREAM_ERROR.

Ориентируйтесь на префикс "Upstream error: " или "Upstream eSIM error: ". Если код вам незнаком, обрабатывайте его как общую ошибку. Некоторые ответы 502 содержат простое описание без кода; если префикса нет, также обрабатывайте их как общую ошибку.

КодЗначение
UPSTREAM_BUSYПровайдер перегружен или ограничивает запросы. Повторите позже с увеличением интервала.
UPSTREAM_REFUSEDПровайдер отклонил запрос. Не повторяйте его без изменений; если ошибка сохраняется, обратитесь в поддержку.
UPSTREAM_PRICE_MISMATCHЦена изменилась с момента, когда вы её получили. Запросите актуальную цену и повторите.
UPSTREAM_INVALID_REQUESTПровайдер счёл запрос недопустимым либо объект не найден (для заказов eSIM пакет). Проверьте параметры запроса, например сервис, страну или пакет.
UPSTREAM_ERRORЛюбой другой сбой на стороне провайдера. Повторите позже.
BANNED_EMAILАдрес электронной почты заблокирован для этого сервиса. Запросите другой адрес.
NO_ACTIVATIONАктивация не найдена у провайдера.
EARLY_CANCEL_DENIEDОтмена пока недоступна. Дождитесь окна отмены и повторите.

Структура ответа об ошибке (JSON)

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 27937
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z

{
  "error": "rate_limit_exceeded",
  "message": "Daily API limit reached. Contact support for higher tier.",
  "retryAfter": 27937,
  "limit": 10000,
  "usage": 10000
}

SMS-Activate текстовые коды

Совместимый с SMS-Activate эндпоинт возвращает plain text коды. Каждый код мапится на HTTP-статус.

Цены указаны в USD, с 3 знаками после запятой, и равны фактически списываемой сумме (прайс-цена до скидки программы лояльности). Цена, которую вы читаете из API, это цена, которую вы платите.

Текст-кодHTTPЗначение
BAD_KEY401Неверный или отсутствующий API-ключ
BAD_ACTION400Параметр action отсутствует или некорректен
BAD_SERVICE400Код сервиса не распознан
BAD_COUNTRY400Параметр country не распознан
BAD_STATUS400Неверное значение status для setStatus
WRONG_ACTION400Имя действия не поддерживается
NO_BALANCE402Недостаточный баланс кошелька
NO_NUMBERS404Нет доступных номеров для этой комбинации
NO_ACTIVATION404ID активации не найден или не ваш
RATE_LIMITED429Превышен rate limit: замедлитесь или дождитесь сброса
REQUEST_LIMIT200С 2026-10-20 (ранее ERROR_SQL): Слишком много одновременных активаций или запросов. Подождите, затем повторите попытку.С 2026-10-20 (ранее ERROR_SQL): HTTP 200, тело ответа в виде простого текста REQUEST_LIMIT — возвращается только SMS-Activate-совместимым эндпоинтом (/stubs/handler_api.php)С 2026-10-20 эндпоинт отвечает REQUEST_LIMIT (до этой даты в таких случаях он отвечает ERROR_SQL). REQUEST_LIMIT охватывает два случая: лимит одновременных активаций и лимит защиты от злоупотреблений.
ERROR_SQL500Внутренняя ошибка сервера: retry позже

Rate Limits

Throttle по API-ключу. Несколько серверов с одним ключом делят одну корзину.

Burst-лимиты

Три параллельных уровня защищают от всплесков и устойчивого злоупотребления. Достижение любого возвращает 429.

short
5
за 1 second
medium
30
за 10 seconds
long
100
за 60 seconds

Дневная квота

По умолчанию 10 000 запросов на API-ключ в день. Сброс в полночь UTC.

  • Публичные эндпоинты каталога (services, countries) освобождены от дневной квоты
  • Счётчик квоты увеличивается при каждом авторизованном запросе, независимо от статуса ответа
  • Pro-уровень с более высокими лимитами доступен: обратитесь в поддержку

Заголовки ответа

Каждый авторизованный ответ содержит rate limit заголовки, чтобы клиенты могли проактивно self-throttle.

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z
Retry-After: 27937

Окно отмены

Каждая активация несёт два поля, которые определяют отмену, поэтому вашему клиенту не нужно узнавать ответ через отклонённый запрос.

cancellableAtЧто это значитDELETE
nullАктивация достигла финального состояния, включая случай с полученным кодом. Отменить её уже нельзя.409
futureПериод ожидания ещё идёт. Отмена откроется в это время.400
pastОтмена доступна сейчас. Поле cancellable равно true.200

Читайте поле, а не прощупывайте эндпоинт

Повтор отклонённого DELETE не изменит ответ. Активация, вернувшая 409, будет возвращать 409 до конца своей жизни, а находящаяся в периоде ожидания будет возвращать 400, пока не наступит cancellableAt.

Пример: отменяйте только тогда, когда API это разрешает

# Read the field instead of probing the endpoint
activation = get(f"/v1/activations/{id}")

if activation["cancellableAt"] is None:
    pass                      # final state, a cancel would answer 409

elif activation["cancellable"]:
    delete(f"/v1/activations/{id}")

else:
    # the cooldown is still running; waiting beats retrying
    sleep(seconds_until(activation["cancellableAt"]))
    delete(f"/v1/activations/{id}")

Стратегия Retry

Как обрабатывать временные сбои, не наводняя API и не теряя данные.

Делайте

  • • Учитывайте заголовок Retry-After в ответах 429
  • • Используйте экспоненциальный backoff для 5xx (1с, 2с, 4с, 8с)
  • • До 5 попыток, затем покажите ошибку пользователю

Не делайте

  • • Не делайте retry для 4xx, кроме 429: они детерминированы
  • • Не молотите API после 429: дождитесь полного Retry-After
  • • Не делайте retry POST /activations без проверки idempotency

Рекомендуемый паттерн retry

# Pseudocode — exponential backoff with Retry-After
attempt = 0
while attempt < 5:
    response = call_api()

    if response.status == 200:
        break  # success

    if response.status == 429:
        wait = response.headers.get('Retry-After', 2 ** attempt)
        sleep(wait)
        attempt += 1
        continue

    if response.status >= 500:
        sleep(2 ** attempt)  # exponential
        attempt += 1
        continue

    raise APIError(response)  # 4xx other than 429

Idempotency

Некоторые операции списывают с кошелька. Наивный retry может привести к двойному списанию.

POST /api/v1/activations не идемпотентен

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

Восстановление после таймаута или неясного ответа

  1. Не отправляйте POST повторно. Вызовите GET /api/v1/activations?status=PENDING,WAITING&limit=50 с тем же API-ключом.
  2. Сопоставьте по service.code, country.isoCode и createdAt в пределах нескольких секунд от времени исходного запроса. Результаты идут от новых к старым; при необходимости переходите по nextCursor.
  3. Step3
  4. Если подходящая активация не появилась в течение 2 минут, можно безопасно купить снова: отправьте новый POST.
  5. Если вы ничего не делаете, активация, не получившая SMS, истекает автоматически и возвращается полностью. refundTxn в списке показывает возврат.

Если вы параллельно выполняете несколько покупок для одного сервиса и страны, сопоставление по времени неточно. Держите не более одной незавершённой покупки на пару сервис/страна.

Изменения

Датированные изменения поведения ошибок. Даты с пометкой «запланировано» ещё не действуют.

2026-10-20 (запланировано)

  • Эндпоинт, совместимый с SMS-Activate, теперь отвечает REQUEST_LIMIT и при лимите одновременных активаций, и при лимите защиты от злоупотреблений (раньше ERROR_SQL).
  • Сообщение об ошибке 502 содержит наш сопоставленный код вместо исходного кода провайдера, как для SMS, так и для eSIM. Формат "Upstream error: <CODE>" (для eSIM "Upstream eSIM error: <CODE>") не меняется.
  • В тело REST-ответа 429 защиты от злоупотреблений добавляется поле code (ANTI_ABUSE_THROTTLE). Это дополнение; существующие поля не меняются.
  • В ответы каталога добавляется новое поле upstreamCode. Прежнее поле кода сервиса в переходный период возвращает то же значение.

Нужно больше деталей?

Интерактивный справочник API показывает ответы ошибок для каждого эндпоинта.