Ошибки и Rate Limits
Полный справочник кодов ошибок, маппинга HTTP, политик rate limit и стратегий retry.
HTTP-коды статусов
Современный REST API использует стандартные HTTP-коды. Тело ответа включает структурированный объект ошибки.
| Код | Статус | Значение |
|---|---|---|
| 400 | Bad Request | Валидация запроса не пройдена (отсутствуют или некорректны параметры) |
| 401 | Unauthorized | Требуется авторизация или ключ API неверен |
| 402 | Payment Required | Недостаточно средств в кошельке для выполнения |
| 403 | Forbidden | Авторизован, но нет прав на этот ресурс |
| 404 | Not Found | Ресурс не найден (например, ID активации не существует) |
| 409 | Conflict | Запрос конфликтует с текущим состоянием |
| 422 | Unprocessable Entity | Запрос корректен по форме, но семантически невалиден |
| 429 | Too Many Requests | Превышен rate limit — см. заголовок Retry-After |
| 500 | Internal Server Error | Неожиданная ошибка сервера — retry с экспоненциальной задержкой |
| 503 | Service Unavailable | Upstream-провайдер недоступен — retry позже |
Структура ответа об ошибке (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-статус.
| Текст-код | 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 — замедлитесь или дождитесь сброса |
| 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Стратегия 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 /activations не идемпотентен
Если вы делаете retry успешного POST /activations, создастся вторая активация и спишется дважды. При любом таймауте или неясном ответе используйте GET /activations для проверки состояния перед retry.
Нужно больше деталей?
Интерактивный справочник API показывает ответы ошибок для каждого эндпоинта.