Статус и поддержка

Диагностируйте до эскалации

Почти каждый заявленный сбой — одно из пяти, и у каждого различимая сигнатура:

Симптом	Вероятная причина	Куда смотреть
`401 unauthorized` на вызове, который вчера работал	Ключ сменён, отключён или заголовок отсутствует на одном из путей кода	Аутентификация
`402 insufficient_balance`	Баланс ниже резерва для этой отправки	Аккаунт и баланс
Один запрос возвращает `200`, но ничего не списано	Вся комбинация не удалась; HTTP-статус — не результат	Биллинг и возвраты
Один и тот же запрос успешен и неуспешен попеременно	Ограничение скорости или `Idempotency-Key`, переиспользуемый для разных полезных нагрузок	Лимиты запросов, Идемпотентность
Пакетная задача висит в `processing`, и `last_progress_at` перестаёт двигаться	Задача действительно зависла, а не просто медленная	Статус задачи

Случай с last_progress_at стоит сказать прямо: сигнал сбоя — не прошедшее время, а остановившаяся метка времени. Задача на 500,000 строк может законно выполняться долго. Задача, у которой last_progress_at не двигается, — это задача для эскалации.

Что приложить к обращению в поддержку

Каждое поле ниже возвращается API, а значит, приложить их ничего не стоит и экономит один обмен:

Приложить	Откуда берётся
`request_id`	Каждый ответ realtime, включая сбои, вернувшие тело
`task_id`	Каждая пакетная отправка и каждый ответ о статусе задачи
`api_key_id`	`GET /v1/api-key` — идентифицирует ключ, не раскрывая его
Точный HTTP-статус и тело ответа	Ваши собственные логи; в особенности поле `code`
Метка времени UTC с секундами	Ваши собственные логи
Отправленный вами запрос со скрытым ключом	Ваш собственный код

Никогда не вставляйте API-ключ в обращение в поддержку. api_key_id идентифицирует ключ, а сам ключ даёт доступ к вашему балансу.

Сообщения об инцидентах

Уведомления уровня аккаунта — плановое обслуживание, деградация ёмкости — появляются в консоли, где также находятся баланс и записи. Теми же условиями API делится с вашей интеграцией напрямую, в виде кодов ошибок, а не прозы:

Код	Что это значит для работающей интеграции
`detection_capacity_unavailable`	Сейчас нет ёмкости. Отступите и повторите; ничего не списано.
`realtime_route_unavailable`	Нет доступного маршрута realtime. Отступите и повторите.
`realtime_rate_limiter_unavailable`	Сам лимитер недоступен, поэтому допуск нельзя решить. Повторите позже.
`realtime_fact_cache_unavailable`	Зависимость realtime недоступна. Повторите позже.

Это 503, и все они в группе «подождать и повторить» — полную группировку, включая то, какие сбои безопасно повторять с тем же Idempotency-Key, см. в Кодах ошибок.

Договорная доступность, условия сервисных кредитов и целевые сроки ответа поддержки определяются отдельным соглашением и здесь не повторяются, поскольку они различаются по тарифам, и обобщённая цифра на странице документации была бы неверна для большинства читателей. Авторитетный источник — ваше соглашение; обратитесь к своему контактному лицу по аккаунту, если это нужно в письменном виде.

Текущее состояние платформы

Два операционных факта проверяемы извне, и их стоит знать до того, как вы заведёте инцидент:

API обслуживается через Cloudflare, поэтому сетевой путь и терминирование TLS обеспечивает Cloudflare, а не один исходный хост.
Каждый ответ несёт X-RateLimit-Remaining, поэтому клиент, логирующий заголовки ответа, может отличить «ограничен собственным лимитом» от «сервис недоступен», никого не спрашивая. Группы general и detection также несут X-RateLimit-Limit в каждом ответе; realtime — нет, потому что тратит token bucket, а не фиксированный потолок в минуту.

Дальше

Коды ошибок — группы повторов, самая быстрая таблица для триажа
Безопасность — обращение с ключом, смена ключа и что никогда не отправлять