Основные понятия

Ошибки

Gemlead отвечает HTTP-статусом и JSON-ошибкой, у которой type и code никогда не меняются, так что ваш код может на них опираться.

Объект ошибки

У всех ошибок одинаковая структура. message написан для людей и может меняться, а type и code предназначены для вашего кода. Каждый ответ, с ошибкой или без, также содержит заголовок Request-Id.

Атрибуты

typestring
Категория ошибки, одна на каждый HTTP-статус.
codestring
Что именно пошло не так. Коды приведены ниже.
messagestring
Понятное человеку описание ошибки.
paramstring или null
Параметр, вызвавший ошибку, если он есть.
request_idstring
ID запроса, тот же, что в его заголовке Request-Id. Сообщите его нам, если нужна помощь.
doc_urlstring
Ссылка на описание кода на этой странице.

Ответ400

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "score_min must be an integer from 0 to 100.",
    "param": "score_min",
    "request_id": "req_7Hq2LmX9pT4vK1sN",
    "doc_url": "https://gemlead.ai/docs/errors#parameter_invalid"
  }
}

Коды HTTP-статусов

Статус	Тип	Значение
400	`invalid_request_error`	В запросе отсутствует, не распознан или неверен параметр. Запрос с методом, который путь не поддерживает, тоже получает этот тип, со статусом 405.
401	`authentication_error`	Ключа нет, ключ неверный или отозван.
403	`permission_error`	Ключ действителен, но не может выполнить это действие, например ключ `read` пытается записать данные или аккаунт на тарифе Free или Starter.
404	`not_found_error`	В аккаунте ключа нет такого объекта или нет такого маршрута.
409	`idempotency_error`	`Idempotency-Key` использован повторно для другого запроса, или его первый запрос ещё выполняется.
429	`rate_limit_error`	Слишком много запросов. Подождите `Retry-After` секунд.
500	`api_error`	Что-то пошло не так на нашей стороне, либо 501, если эндпоинт ещё недоступен. Повторите позже с тем же `Idempotency-Key`.

Коды ошибок

Код	Статус	Значение
`api_key_missing`	401	В запросе нет заголовка `Authorization` или `X-Api-Key`.
`api_key_invalid`	401	Такого ключа нет. Проверьте, что скопировали его целиком, включая `gl_live_`.
`api_key_revoked`	401	Ключ отозван в приложении. Создайте новый.
`token_expired`	401	Истёк срок действия OAuth-токена доступа ИИ-ассистента. Ассистент обновит его сам.
`insufficient_scope`	403	У ключа только право `read`, а запрос меняет данные. Используйте ключ с правом `write`.
`plan_required`	403	Владелец аккаунта на тарифе Free или Starter. API работает на тарифах Business и Enterprise, включая пробный период, и тот же ключ снова заработает, как только аккаунт перейдёт на один из них.
`forbidden`	403	Пользователю ключа это действие в этом аккаунте X недоступно. Например, участник без роли админа меняет команду или делится персоной.
`parameter_missing`	400	Отсутствует обязательный параметр. Название параметра указано в `param`.
`parameter_invalid`	400	API не принимает значение параметра, например оценку выше 100 или дату не в формате ISO 8601. Название параметра указано в `param`.
`parameter_unknown`	400	В строке запроса или в теле есть параметр, который этот эндпоинт не принимает. Название параметра указано в `param`.
`body_invalid`	400	Тело не является корректным JSON или JSON-объектом.
`cursor_invalid`	400	Этот `cursor` не был выдан API или создан для других фильтров.
`idempotency_key_invalid`	400	`Idempotency-Key` длиннее 255 символов.
`method_not_allowed`	405	Этот путь не поддерживает данный метод. Допустимые методы перечислены в заголовке `Allow`.
`url_invalid`	400	URL вебхука не на HTTPS, содержит учётные данные, не резолвится или указывает на частный адрес.
`webhook_endpoint_limit_reached`	400	У аккаунта уже 10 эндпоинтов вебхуков. Сначала удалите один.
`resource_already_exists`	400	Такой объект уже существует, например у персоны уже есть источник с этим методом или такой же поиск по ключевым словам.
`limit_reached`	400	Достигнут лимит, например 100 персон на аккаунт, 500 поисков по ключевым словам на персону или 50 колонок доски.
`seed_source_refused`	400	Стартовый источник новой персоны отклонён, например аккаунт инвестора, акселератора или СМИ. Такие источники не приводят покупателей.
`x_profile_not_found`	400	В X нет доступного профиля с таким именем пользователя.
`lead_without_x_id`	400	У лида ещё нет ID аккаунта X, поэтому подписаться на него нельзя.
`lead_not_convertible`	400	Лид не относится ни к одной персоне, поэтому не может стать источником.
`campaign_archived`	400	Кампания в архиве. Скопируйте её, чтобы запустить снова.
`campaign_not_started`	400	Кампания ещё черновик, поэтому приостанавливать нечего.
`campaign_flow_empty`	400	В сценарии кампании ещё нет ни одного шага. Добавьте шаг, прежде чем запускать её.
`column_protected`	400	Эта колонка входит в саму доску, например «Входящие» или колонка персоны, и её нельзя удалить.
`shared_account_has_campaigns`	400	У аккаунта X, который вы убираете из общей персоны, ещё есть кампании по этой персоне. Удалите их и попробуйте снова.
`owner_cannot_leave`	400	Владелец аккаунта X не может выйти из своей команды. Вместо этого удалите участников.
`translation_off`	400	Перевод диалога выключен. Включите его или переводите по одному сообщению.
`recipient_not_messageable`	400	X отклонил DM. Лид закрыл DM или заблокировал аккаунт.
`media_kind_unsupported`	400	Этот диалог не принимает такой тип файла. Для голосового сообщения нужен диалог в X Chat.
`x_session_expired`	409	Сессия аккаунта X истекла. Переподключите его в приложении и повторите попытку.
`assistant_busy`	409	Julien AI ещё отвечает на сообщение в этом чате или на 3 сообщения этого аккаунта X. Дождитесь ответа и отправьте снова.
`conversation_unavailable`	409	В диалоге пока нет пользователя X, которому можно написать.
`resource_missing`	404	В аккаунте ключа нет объекта с этим ID. На ID из другого аккаунта ответ такой же.
`route_not_found`	404	По этому пути нет эндпоинта.
`idempotency_key_reused`	409	Этот `Idempotency-Key` уже использовался за последние 24 часа для другого метода, пути или тела.
`idempotency_key_in_use`	409	Первый запрос с этим `Idempotency-Key` ещё выполняется. Повторите через секунду.
`rate_limit_exceeded`	429	Больше 120 запросов в минуту с этим ключом. Подождите `Retry-After` секунд.
`export_rate_limit_exceeded`	429	Больше 10 экспортов в час на этом аккаунте.
`dm_paused`	429	X временно ограничивает DM аккаунта. `Retry-After` показывает, когда они снова станут доступны.
`dm_rate_limited`	429	Больше 10 DM в минуту с этого аккаунта.
`dm_daily_limit`	429	С этого аккаунта уже отправлено 300 DM за сегодняшние сутки по UTC или исчерпана его суточная квота в X.
`assistant_rate_limited`	429	Больше 6 сообщений Julien AI в минуту с этого аккаунта X или 150 в час для его владельца, включая чат в приложении.
`assistant_daily_limit`	429	С этого аккаунта X уже отправлено 100 сообщений Julien AI за сегодняшние сутки по UTC.
`passcode_rate_limited`	429	Больше 5 попыток ввода кода X Chat в час на этом аккаунте. X учитывает каждую попытку.
`internal_error`	500	Непредвиденная ошибка на нашей стороне. `request_id` поможет нам её найти.
`request_timeout`	500	Запрос выполнялся слишком долго. Повторите его, а если он меняет данные, то с тем же `Idempotency-Key`.
`not_implemented`	501	Этот эндпоинт пока недоступен.
`upstream_unavailable`	502	X или сервис Gemlead не ответил. Ничего не изменилось, повторите через минуту.

Обработка ошибок

400, 401, 403 и 404 в неизменном виде никогда не пройдут. Исправьте запрос, прежде чем отправлять его снова.
409 с idempotency_key_in_use пройдёт через секунду. Повторите запрос с тем же Idempotency-Key.
429 пройдёт через Retry-After секунд. См. раздел Лимиты запросов.
500 можно повторить после короткой паузы. Для запросов, которые меняют данные, передавайте тот же Idempotency-Key, чтобы ничего не выполнилось дважды.
Записывайте в лог request_id каждой ошибки, по нему мы найдём запрос за секунды.