Коды ошибок

Все ошибки возвращаются как JSON:

{
  "error": "<machine_code>",
  "message": "<human-readable>"
}

(У некоторых endpoint'ов поле называется reason — это всё то же самое.)

Auth / signature (401, 403)

error	HTTP	Что значит	Как чинить
missing_bearer	401	Нет Authorization: Bearer ....	Добавьте заголовок.
invalid_api_key	401	Ключ не найден / партнёр paused / archived.	Сверьте, что используете актуальный ключ.
missing_timestamp	401	Нет X-Timestamp или не число.	Передайте unix-секунды.
timestamp_out_of_range	401	Дрифт >300 секунд.	Синхронизируйте время (NTP).
bad_signature	403	X-Signature не сходится с тем, что считаем мы.	См. HMAC подпись, особенно про raw body.
ip_not_allowed	403	IP не в whitelist (если включён).	Добавьте IP через менеджера.

Validation (422)

status ≡ validation_error. Поле reason имеет формат missing_required:<field> или invalid:<field>:<details>.

reason	Что значит
missing_required:phone	Поле phone пустое или отсутствует.
invalid:phone:format	Не похоже на телефон.
invalid:email:format	Не похоже на email.
invalid:country:unknown	Указан несуществующий ISO-код страны.
payload_too_large	Body >100 KB.
unsupported_content_type	Content-Type не application/json.

Business rules (422)

status ≡ rejected. Финальное состояние — попыток создать лид больше не будет.

reason	Что значит
country_blocked:<XX>	Страна в bla(c)k-листе вашего партнёра.
source_blocked:<x>	Источник запрещён.
phone_blacklisted	Номер в нашем глобальном blacklist'е (DNC / fraud).
affiliate_paused	Ваш партнёр временно остановлен менеджером.
no_active_agents	Нет доступных агентов для распределения.

Duplicate (409)

status ≡ duplicate. Возвращается id существующего лида.

reason	Что значит
matched_lead:<id>	Совпадение по phone или email в окне дедупликации.

Rate limit (429)

{
  "error": "rate_limit_exceeded",
  "message": "Try again in 18 seconds"
}

Заголовок Retry-After содержит время до разблокировки. См. Rate limits.

Server (5xx)

Если вы регулярно получаете 5xx — это наша проблема, напишите менеджеру. В норме 5xx бывает ≤ 0.01% от общего объёма.

{
  "error": "internal_error",
  "message": "Something went wrong on our side"
}

В этом случае:

• Не считайте лид обработанным.
• Подождите 30–60 секунд.
• Повторите запрос с тем же Idempotency-Key.
• Если 3 повтора подряд получили 5xx — пишите менеджеру в Telegram.

Что делать с unknown reason

Если вы поймали reason, которого нет в этой таблице — это либо:

1. Кастомное правило, добавленное под вашего партнёра. Спросите менеджера, что значит.
2. Баг с нашей стороны — пришлите нам external_id лида, мы посмотрим.

Не пытайтесь регекспить reason — это строка для человека-отладчика, формат может расширяться. Используйте status (accepted/duplicate/validation_error/rejected) для машинной логики.