Ошибки и повторы
Формат ошибок, коды статусов и лимиты.
Формат
Ошибки биллинг-API обычно имеют следующий конверт. У API генерации также есть поля code, message и data; проверяйте контракт конкретного метода:
{
"statusCode": 400,
"message": "duration must be an integer number"
}statusCode— HTTP-код;message— строка или массив строк (ошибки валидации);code— машиночитаемый код (не всегда присутствует).
Коды
| Код | Когда |
|---|---|
| 400 | Неверные параметры запроса (валидация DTO) |
| 401 | Нет ключа / ключ неизвестен или деактивирован |
| 403 | Legacy service-ключ; доступ запрещён |
| 404 | Ресурс не найден |
| 429 | Превышен лимит. Для биллинга/вебхуков по умолчанию 60/мин на API-ключ, для сессии — на партнёра. Есть дополнительные IP-лимиты: таблица. Учитывайте Retry-After, если он присутствует |
| 500 | Внутренняя ошибка; исход изменяющей операции может быть неизвестен. Правила повторов — ниже |
Валидация
Глобальный валидационный пайплайн отбрасывает неизвестные поля и приводит типы. Массив message перечисляет все нарушения сразу:
{
"statusCode": 400,
"message": [
"duration must be an integer number",
"resolution must be shorter than or equal to 16 characters"
]
}Рекомендации по ретраям
| Операция | После 429, 5xx или сетевого таймаута |
|---|---|
| Чтение баланса, истории, статуса задачи | Повторяйте с ограничением числа попыток и экспоненциальной задержкой; учитывайте Retry-After |
POST /v1/billing/pricing/estimate | Оценка не запускает задачу и не резервирует баланс; допустим ограниченный повтор |
POST /v1/billing/payment/link | Сохраняйте исходные Idempotency-Key и сумму; не создавайте новый ключ для повторной попытки той же операции. Конфликт суммы — 409 |
| Запуск генерации | Не повторяйте автоматически. Если есть data.task_id, проверяйте эту задачу. Успешное списание или его отсутствие не доказывает, что провайдер не принял запрос |
| Создание счёта или регистрация вебхука | Сначала проверьте историю счетов / список эндпоинтов; общего обещания идемпотентности здесь нет |
| Повтор доставки вебхука | Сначала проверьте получателя и историю доставки. Replay сохраняет eventId; обработчик обязан дедуплицировать событие |
Для 401/403 исправьте авторизацию; повтор без изменения ключа или сессии не поможет. Для 400 исправьте параметры. Не продолжайте бесконечный polling: ограничьте время ожидания и сохраните идентификатор для последующей проверки.
Неизвестный исход запуска
Если ответ запуска потерян и task_id отсутствует, не отправляйте новый платный запрос. Проверьте историю задач в кабинете и обратитесь через контакты Apergrex. Передайте время UTC, путь API, HTTP-код и известные идентификаторы. Не передавайте API-ключ, cookie, подпись или секрет вебхука.