Ошибки и Rate Limits
Полный справочник кодов ошибок, маппинга HTTP, политик rate limit и стратегий retry.
HTTP-коды статусов
Современный REST API использует стандартные HTTP-коды. Тело ответа включает структурированный объект ошибки.
| Код | Статус | Значение |
|---|---|---|
| 400 | Bad Request | Валидация запроса не пройдена (отсутствуют или некорректны параметры) |
| 400 | Bad Request | Неверный формат сайта для email (код EMAIL_SITE_INVALID): относится к созданию email-активации и повторному заказу. Ранее в этом случае возвращался 500. |
| 401 | Unauthorized | Требуется авторизация или ключ API неверен |
| 402 | Payment Required | Недостаточно средств в кошельке для выполнения |
| 403 | Forbidden | Авторизован, но нет прав на этот ресурс |
| 404 | Not Found | Ресурс не найден (например, ID активации не существует) |
| 409 | Conflict | Запрос конфликтует с текущим состоянием |
| 422 | Unprocessable Entity | Запрос корректен по форме, но семантически невалиден |
| 422 | Unprocessable Entity | Сайт для email не поддерживается (код EMAIL_SITE_NOT_SUPPORTED): относится к созданию email-активации и повторному заказу. Ранее в этом случае возвращался 500. |
| 429 | Too Many Requests | Превышен rate limit: см. заголовок Retry-After |
| 429 | Too Many Requests | Лимит одновременных активаций: JSON-код ACTIVATION_CONCURRENCY_LIMIT (поля limit, open). Подождите, затем повторите попытку. |
| 429 | Too Many Requests | Лимит защиты от злоупотреблений (error "Too Many Requests"; с 2026-10-20 в JSON-теле также есть код ANTI_ABUSE_THROTTLE). Временно применяется, если аккаунт за недавний период запросил много номеров, отменил почти все и не получил ни одного кода. Используйте имеющиеся номера или подождите, затем повторите попытку. |
| 500 | Internal Server Error | Неожиданная ошибка сервера: retry с экспоненциальной задержкой |
| 502 | Bad Gateway | Сбой на стороне вышестоящего провайдера. Сообщение в теле обычно имеет вид "Upstream error: <CODE>" (для заказов eSIM "Upstream eSIM error: <CODE>"). С 2026-10-20 <CODE> один из кодов ниже; до этой даты это может быть необработанный код. |
| 503 | Service Unavailable | Upstream-провайдер недоступен: 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_KEY | 401 | Неверный или отсутствующий API-ключ |
| BAD_ACTION | 400 | Параметр action отсутствует или некорректен |
| BAD_SERVICE | 400 | Код сервиса не распознан |
| BAD_COUNTRY | 400 | Параметр country не распознан |
| BAD_STATUS | 400 | Неверное значение status для setStatus |
| WRONG_ACTION | 400 | Имя действия не поддерживается |
| NO_BALANCE | 402 | Недостаточный баланс кошелька |
| NO_NUMBERS | 404 | Нет доступных номеров для этой комбинации |
| NO_ACTIVATION | 404 | ID активации не найден или не ваш |
| RATE_LIMITED | 429 | Превышен rate limit: замедлитесь или дождитесь сброса |
| REQUEST_LIMIT | 200 | С 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_SQL | 500 | Внутренняя ошибка сервера: retry позже |
Rate Limits
Throttle по API-ключу. Несколько серверов с одним ключом делят одну корзину.
Burst-лимиты
Три параллельных уровня защищают от всплесков и устойчивого злоупотребления. Достижение любого возвращает 429.
Дневная квота
По умолчанию 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 429Idempotency
Некоторые операции списывают с кошелька. Наивный retry может привести к двойному списанию.
POST /api/v1/activations не идемпотентен
Повторный запрос, который сервер уже обработал, создаёт вторую активацию и второе списание. Никогда не повторяйте запрос вслепую после таймаута или ошибки соединения.
Восстановление после таймаута или неясного ответа
- Не отправляйте POST повторно. Вызовите
GET /api/v1/activations?status=PENDING,WAITING&limit=50с тем же API-ключом. - Сопоставьте по
service.code,country.isoCodeиcreatedAtв пределах нескольких секунд от времени исходного запроса. Результаты идут от новых к старым; при необходимости переходите поnextCursor. - Step3
- Если подходящая активация не появилась в течение 2 минут, можно безопасно купить снова: отправьте новый POST.
- Если вы ничего не делаете, активация, не получившая 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 показывает ответы ошибок для каждого эндпоинта.