Ошибки API: что означает каждый код и как обрабатывать ответ
Когда лид не принят, сеть возвращает код причины. От того, как вы обрабатываете коды, зависит, потеряете ли вы заявки и бюджет. Разбираем каждый код и правильную реакцию.
Как устроен ответ с ошибкой
Если лид не принят, API отвечает HTTP-кодом 4xx и телом в формате JSON:
{ "status": "error", "code": "limit_reached", "message": "Лимит лидов на сегодня по этому офферу и городу исчерпан" }Главное поле для обработки — code. Текст в message предназначен для человека, и его формулировки могут меняться, поэтому логику строите по коду, а не по тексту.
Таблица кодов
| Код | HTTP | Причина | Реакция |
|---|---|---|---|
| bad_request | 400 | Нет обязательных полей | Исправить запрос |
| bad_key | 401 | Неверные wmkey или apikey | Проверить ключи |
| blocked | 403 | Аккаунт заблокирован | Написать менеджеру |
| geo_closed | 403 | Город по офферу не открыт | Не лить на этот город |
| offer_not_found | 404 | Оффера нет | Проверить offer_id |
| offer_not_live | 409 | Оффер на паузе или остановлен | Остановить трафик |
| duplicate | 409 | Телефон уже был за 30 дней | Не повторять |
| city_not_found | 422 | Город не распознан | Исправить название |
| bad_phone | 422 | Телефон битый | Показать ошибку пользователю |
| limit_reached | 429 | Лимит на сегодня исчерпан | Остановить или перенаправить |
Ошибки конфигурации: чинятся один раз
Коды bad_request, bad_key, offer_not_found и city_not_found говорят о неверной настройке интеграции. Они возникают сразу при первых запросах и, как правило, исчезают после исправления. Если вы вдруг получили bad_key на ранее работавшей интеграции, возможно, ключ перевыпущен: старый apikey перестаёт работать немедленно. Загляните в кабинет и обновите ключ в настройках сервера.
Ошибки состояния: решает бизнес-логика
- offer_not_live. Оффер на паузе или остановлен. Причина может быть в том, что у клиники закончились деньги и приём остановлен (код client_no_funds), либо оффер приостановлен менеджером. Не лейте трафик, пока статус не изменится, и следите за кабинетом.
- limit_reached. Дневной лимит по городу исчерпан, сутки считаются по Москве. Лиды завтра приниматься снова. Разумно автоматически выключить кампании по этому городу до следующего дня.
- geo_closed. Город не открыт вам по офферу. Проверьте список разрешённых гео в оффере.
- blocked. Аккаунт заблокирован. Обратитесь к менеджеру через контакты.
Ошибки данных пользователя
Коды bad_phone и duplicate относятся к конкретной заявке. С bad_phone покажите человеку, что номер введён неверно, и дайте исправить его на форме. С duplicate заявка не нужна клинике: человек уже приходил по этому офферу за 30 дней, и повторная отправка не изменит результат. Не показывайте пользователю технические детали: достаточно нейтрального «Мы уже получили вашу заявку».
Что повторять, а что нет
Повторять запрос имеет смысл только при сетевой ошибке и ответе 5xx. Любой 4xx вернёт ту же ошибку. Исключение из логики: limit_reached и offer_not_live меняются со временем, но повторять их через секунды бесполезно. Лучше записать заявку в очередь и вернуться к ней, когда ситуация изменится, или остановить кампанию.
switch (response.code) {
case 'limit_reached':
case 'offer_not_live': pauseCampaign(city); break;
case 'duplicate': markAsDuplicate(lead); break;
case 'bad_phone': askUserToFixPhone(); break;
default: alertDeveloper(response);
}
Как не потерять информацию об ошибках
- Записывайте в журнал код, время, номер оффера и город.
- Раз в день смотрите сводку по кодам: рост limit_reached показывает, что вы упираетесь в лимит.
- Настройте оповещение при bad_key и blocked: это срочные проблемы.
- Не показывайте пользователю код ошибки сети.
Пример журнала ошибок и разбора за неделю
Ведите простую таблицу или лог, где каждая неудачная отправка записывается с кодом. Раз в неделю смотрите, какие коды встречаются чаще всего. Условный пример результата анализа (цифры выдуманы для иллюстрации): значительная часть отказов приходится на limit_reached по двум городам. Это говорит о том, что трафик по этим городам превышает лимит оффера, а значит, часть рекламного бюджета уходит в никуда. Решение: уменьшить ставки или бюджеты по этим городам в конце дня либо переключить трафик на соседние города с остатком лимита.
Другая картина: много bad_phone. Тогда проблема в форме: возможно, нет маски ввода, и люди пишут номер в странном виде, либо поле используют боты. В таком случае добавьте проверку на лендинге и отсеките нецелевой трафик, а при подозрении на ботов включите фильтры в трекере.
Что показывать пользователю
Пациенту не нужны технические коды. Сопоставьте каждому коду понятное сообщение или молчание. Для bad_phone: «Проверьте номер телефона». Для duplicate: «Мы уже получили вашу заявку, с вами свяжутся». Для limit_reached и offer_not_live пользователю лучше показать нейтральное «Спасибо, заявка принята» только если вы действительно сохранили её у себя для последующей отправки. Нельзя обманывать человека: если заявка не будет передана клинике, честнее сообщить, что приём временно недоступен, и предложить позвонить по телефону клиники, который есть на вашей странице.
Ошибки, которые не бывают на стороне сети
Не все сбои связаны с кодами из таблицы. Сетевая недоступность, истёкший сертификат на вашей стороне, зависший прокси или неправильный DNS приводят к тому, что запрос вообще не доходит. В таком случае кода сети у вас не будет, и обработчик должен отличать «получил ответ с ошибкой» от «не получил ответа». Первое решается исправлением данных, второе повтором запроса с тем же apiid и поиском проблемы в инфраструктуре.
Коротко
Код ошибки важнее текста сообщения. Ошибки конфигурации чинятся один раз, ошибки состояния требуют остановки трафика, ошибки данных требуют реакции на форме.
Вопросы и ответы
Какие ошибки считать критическими?
bad_key, blocked и offer_not_found. Они означают, что интеграция не работает вовсе, и каждая минута простоя стоит трафика.
Что значит client_no_funds?
У клиники не хватает свободных денег, приём заявок остановлен. Вебмастер видит в кабинете, что оффер на паузе. Пока клиника не пополнит предоплату, лиды не принимаются.
Зачем ошибка duplicate, если я отправил заявку впервые?
Этот телефон уже приходил по этому офферу за последние 30 дней, возможно, от другого вебмастера. Клиника не платит за дубли.
Можно ли получить список ошибок заранее?
Все коды перечислены в документации API. Заведите в коде обработку каждого и ветку по умолчанию для новых.
Нужно ли уведомлять менеджера об ошибках?
О единичных ошибках нет. Но если вы видите blocked, постоянный offer_not_live без объяснимой причины или массовый bad_key после перевыпуска ключа, напишите менеджеру: он быстрее разберётся в причине.