Recca Поддержка
Меню

Коды ошибок постбэка: что значат и что делать

Ответы приёма постбэков Recca: что означает каждый код ошибки (INVALID_INPUT, BAD_SIGNATURE и другие), где найти его и как исправить.

Когда сеть не принимает постбэк, она отвечает HTTP-кодом и телом с кодом ошибки: {"success": false, "error": {"code": "BAD_SIGNATURE", "message": "…"}}. Ищите значение поля error.code и сверяйте его с таблицей ниже. Эти же отказы видны в журнале: в кабинете рекламодателя откройте «Приём результата (S2S)», в блоке «Журнал постбеков» нажмите «Открыть журнал» и включите фильтр «С ошибкой». Журнал хранит запросы за последние 90 дней.

Коды ошибок

INVALID_INPUT · HTTP 400

Не хватает обязательного поля либо значение не проходит проверку: нет click_id, external_id или status; сумма не число или больше допустимого; sub_id длиннее 200 символов; код цели содержит недопустимые символы.

Что делать: Сверьте отправляемые поля со списком в статье «Поля, синонимы и макросы». Частая причина — макрос CRM не подставился и уехал в запрос как есть (sum={cost_money_value}).

OFFER_NOT_FOUND · HTTP 400

В адресе указан идентификатор оффера, которого нет, либо у оффера не заведены условия CPA и секрет.

Что делать: Возьмите адрес постбэка со страницы «Приём результата (S2S)» — там он готовый, для каждого вашего оффера. Такой запрос не попадает в журнал: он не принадлежит ни одной сети.

BAD_SIGNATURE · HTTP 403

Подпись в заголовке X-CPA-Signature не совпала с той, что ожидает сеть: другой секрет либо строка собрана в другом порядке.

Что делать: Проверьте секрет виджетом «Проверить интеграцию» — он подписывает тестовый постбэк ИМЕННО тем секретом, который вы вставите, и прогоняет через боевой приёмник. Если секрет верный — проверьте порядок полей в строке подписи и то, что пустые значения остаются пустыми сегментами.

BAD_SECURE · HTTP 403

В GET-ссылке параметр secure не совпал с токеном оффера. ⚠ С WV-0740 туда вставляется НЕ секрет подписи, а отдельный токен вида cpag_…: строка запроса целиком попадает в журналы промежуточных серверов, и ключу, которым подписывается тело, там не место.

Что делать: Токен выдаётся вместе с секретом — при создании оффера и при каждой ротации, один раз. Если он утерян, выпустите новый секрет на странице S2S: токен перевыпустится вместе с ним. Прежнее значение параметра (сам секрет) больше не принимается — это не переходный период, а смена контракта.

STALE_SIGNATURE · HTTP 403

Подпись верна, но заголовок X-CPA-Timestamp вне окна свежести — пять минут в обе стороны — либо не является меткой времени Unix в секундах.

Что делать: Сверьте часы сервера, с которого уходят постбэки: окно двустороннее, поэтому спешащие часы отбиваются так же, как отстающие. Если вы повторяете отложенный постбэк из очереди — подписывайте его ЗАНОВО с текущей меткой, а не отправляйте сохранённое тело со старой.

UNKNOWN_KEY_ID · HTTP 403

Заголовок X-CPA-Key-Id назвал слот секрета, которого не существует. Допустимы current и previous.

Что делать: Заголовок необязателен: без него сеть проверяет оба слота сама. Присылайте его, только если точно знаете, каким ключом подписали; неизвестное значение отбивается намеренно, иначе заголовок ничего не означал бы.

WINDOW_EXPIRED · HTTP 409

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

Что делать: Смотрите «Окно атрибуции» в условиях оффера. Если ваш цикл сделки длиннее окна — договоритесь с сетью об увеличении, задним числом конверсия не засчитывается.

ALREADY_CONVERTED · HTTP 409

По этому переходу уже засчитана конверсия на ту же цель, но с другим номером заказа. Один клик оплачивается один раз на цель.

Что делать: Если это продолжение воронки — пришлите постбэк с другой целью (goal), а не с новым номером заказа. Если это тот же заказ — отправьте прежний external_id, и повтор попадёт в идемпотентность.

ILLEGAL_TRANSITION · HTTP 409

Запрошенный переход статуса невозможен: например, подтвердить конверсию, по которой уже прошёл возврат.

Что делать: Посмотрите текущий статус заказа в сверке. Отменённая конверсия терминальна — новое подтверждение оформляется новым external_id.

UNKNOWN_GOAL · HTTP 400

В постбэке указана цель, которой у оффера нет.

Что делать: Список целей оффера — на странице S2S под ставкой. Сеть намеренно не подставляет ставку «по умолчанию» вместо неизвестной цели: заплатить по чужой ставке хуже, чем отказать.

GOAL_DISABLED · HTTP 409

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

Что делать: Это состояние конфликта, а не кривой запрос: ставки и история цели сохранены, но приём остановлен. Попросите оператора включить цель на странице целей оффера либо шлите другую цель. Уже записанные конверсии по ней подтверждаются и возвращаются как раньше — отказ касается только новых.

EXTERNAL_ID_CONFLICT · HTTP 409

Этот номер заказа уже занят в сети по этой же цели — но другим оффером, не вашим.

Что делать: Номер заказа уникален в пределах СЕТИ, а не оффера, поэтому у двух рекламодателей со сквозной нумерацией с единицы номера пересекутся. Добавьте к external_id собственный префикс. Раньше в этом случае постбэк молча переписывал чужую конверсию, поэтому отказ — это не новое ограничение, а прекращение тихой порчи данных.

IDEMPOTENT_MISMATCH · HTTP 409

Постбэк по этому заказу и этой цели уже приходил, но с ДРУГОЙ суммой. Раньше такой повтор получал успех и прежние деньги — то есть сеть подтверждала сумму, которой не начисляла.

Что делать: Сумма — часть операции, а не её уточнение. Если сумма изменилась (доплата, пересчёт, частичный возврат), это ДРУГОЕ событие: пришлите его под своим external_id. Если это добросовестный повтор — пришлите ту же сумму, и он попадёт в идемпотентность. ⚠ «Не передали сумму» и «передали ноль» — разные значения: постбэк без sum_rub не совпадает с постбэком, где sum_rub=0.

NOT_CONVERTED · HTTP 400

Рекламодатель прислал отмену (статус «отклонено») по заказу, у которого по этой цели ещё не было подтверждения. Это штатный исход, а не сбой: отмена записана (строка «отклонено»), и подтверждение по этому заказу и цели уже не пройдёт. Снаружи ответ всегда 400 — он одинаков для «заказа не было» и «был, но не засчитан», чтобы по ответу нельзя было перебирать чужие номера заказов.

Что делать: Действий не требуется, если рекламодатель и должен был отклонить этот заказ (например, цель «сделка провалена»). Ошибка — только если вы ждали ПОДТВЕРЖДЕНИЕ по этому заказу: тогда проверьте в журнале, что подтверждение и отмена идут с одним номером заказа и одной целью — отмена ищет конверсию по тройке «сеть + номер заказа + цель».

NOT_FOUND · HTTP 404

Денежная нога отменяемой конверсии не найдена — отменять нечего.

Что делать: Как правило, конверсия уже отменена. Проверьте статус в сверке: повторная отмена безопасна и ничего не меняет.

REVERSAL_FAILED · HTTP 500

Возврат начался, но не завершился на нашей стороне.

Что делать: Повторите запрос: операция идемпотентна. Если повторяется — сообщите оператору сети время запроса и номер заказа, строка есть в журнале.

RATE_LIMITED · HTTP 429

Превышен лимит обращений. Вёдер ДВА, и исчерпать достаточно одно: по офферу — 60 запросов в минуту, по адресу отправителя — 300. Ответ несёт заголовок Retry-After с паузой в секундах.

Что делать: Ставьте постбэки в очередь и берите паузу из Retry-After, а не из своей константы. Лимит общий для обеих дверей (POST и GET) — переезд на другой транспорт его не обходит. ⚠ Ведро оффера считается по идентификатору в адресе: несколько ваших офферов не мешают друг другу, а вот один оффер, нагруженный с нескольких серверов, делит общий счёт.

INTERNAL_ERROR · HTTP 500

Сбой на нашей стороне: запрос дошёл, но обработать его не удалось. Конверсия при этом не создана.

Что делать: Повторите запрос позже: приёмник идемпотентен, дубликат не создаст вторую конверсию. Если повторяется — напишите оператору сети.

Как проверить исправление

На странице «Приём результата (S2S)» нажмите «Проверить интеграцию»: виджет прогонит тестовый постбэк через боевой приёмник и покажет итог. Затем отправьте настоящий постбэк и убедитесь, что он появился в «Журнале постбеков».