Ошибки

API отвечает кодами HTTP: 2xx - запрос выполнен, 4xx - ошибка в запросе, 5xx - сбой на нашей стороне. Тело ошибки - JSON в формате RFC 7807.

Формат ошибки

{
  "type": "https://dialogi.io/errors/unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "detail": "Invalid, expired or revoked API key.",
  "request_id": "req_4WHRB5tCR3dmQk9nOr3ibwfx"
}

Пример ошибки 422 с полем errors:

{
  "type": "https://dialogi.io/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Если код ошибки в type вам незнаком, решайте по status. При сбое на нашей стороне (5xx) тело может прийти в другом формате - тогда ориентируйтесь только на статус.

Request-Id

В ответе на любой запрос к ресурсу API есть заголовок Request-Id:

Request-Id: req_4WHRB5tCR3dmQk9nOr3ibwfx

Записывайте его в свои логи. Если пишете в поддержку о конкретном запросе, приложите Request-Id.

Можно передать свой идентификатор в заголовке X-Request-ID - тогда Request-Id будет req_ и ваше значение. Так запрос проще связать с логами вашей системы.

Коды ошибок

Коды заявок на звонок, записей и диалогов - в разделах Заявки на звонок, Записи и Диалоги ниже.

bad-request

400. Запрос составлен так, что его нельзя выполнить. Что именно не так - в detail. Исправьте запрос и отправьте снова.

idempotency-key-required

400. В запросе на создание нет заголовка Idempotency-Key. Добавьте его - см. Идемпотентность.

idempotency-key-invalid

400. Ключ идемпотентности длиннее 64 символов, пустой или содержит недопустимые символы. Разрешены латинские буквы, цифры и символы _ - : ..

unauthenticated

401. Нет заголовка Authorization: Bearer dk_live_…, ключ скопирован с ошибкой, истёк после перевыпуска или отозван. Проверьте ключ в личном кабинете: «Настройки» → «Разработчикам». Повторять запрос с тем же ключом бесполезно.

api-addon-required

402. У компании не подключено дополнение «Публичный API». Подключите его в личном кабинете: «Оплата» → «Тариф» → «Дополнительно». После подключения ключ начинает работать в течение минуты.

forbidden

403. Ключ рабочий, но этот запрос ему не разрешён:

• у ключа нет нужного права - в detail указано, какого именно;
• project_id в запросе - проект, которого нет в ключе;
• у ключа не осталось ни одного проекта, например все его проекты удалены;
• ключ отправлен на адрес, который не входит в публичный API.

Права и проекты ключа не меняются - создайте ключ с нужным доступом. См. Ключи и права.

not-found

404. Объекта с таким id нет, он удалён или находится в проекте, которого нет в ключе. Та же ошибка приходит на адрес, которого нет в API, например с опечаткой в названии ресурса.

conflict

409. Действие противоречит текущему состоянию данных. Подробность - в detail. Перечитайте объект и решите, нужно ли действие.

idempotency-conflict

409. Этот Idempotency-Key уже использован с другим запросом: другое тело, метод или адрес. Для нового запроса нужен новый ключ.

idempotency-in-progress

409. Первый запрос с этим Idempotency-Key ещё выполняется. Повторите через пару секунд с тем же ключом - получите его результат.

validation

422. Данные запроса не прошли проверку: нет обязательного поля, неверный формат, значение вне списка допустимых. Список полей с ошибками - в errors. Поле errors бывает не всегда - иногда пояснение только в detail, например когда у ключа несколько проектов, а project_id не передан.

Ошибка не запоминается ключом идемпотентности: исправьте тело и повторите запрос с тем же Idempotency-Key.

rate-limited

429. Превышен лимит запросов. Через сколько секунд можно повторить, указано в заголовке Retry-After. См. Лимиты запросов.

unavailable

503. Сервис временно не может обработать запрос. Повторите позже с нарастающей паузой. Запрос на создание повторяйте с тем же Idempotency-Key.

internal

500. Ошибка на нашей стороне. Повторите запрос позже - запрос на создание с тем же Idempotency-Key. Если ошибка повторяется, напишите в поддержку и приложите request_id.

http

Прочие ответы HTTP, у которых нет своего кода, например 405, если метод не поддерживается для этого адреса. Смотрите status и detail.

Заявки на звонок

perezvoni-not-configured

409. В проекте не настроен Перезвони, поэтому заявку некому передать и звонок не состоится. Включите и настройте Перезвони в этом проекте в личном кабинете, затем повторите запрос.

Записи

В ошибках записей, кроме type, есть поле code - тот же код, записанный через подчёркивание: slot_unavailable.

slot-unavailable

409. Это время уже занято. У услуг fixed та же ошибка приходит, если у ресурса не хватает свободных мест на всех гостей: число гостей ограничивает capacity ресурса. Запросите свободные слоты с тем же числом гостей (guests) и выберите другое время.

outside-working-hours

409. Время не попадает в график работы филиала или исполнителя. Свободные слоты уже учитывают график.

no-resources

409. В выбранном филиале нет ни одного исполнителя, который оказывает эту услугу.

appointment-not-reschedulable

409. Запись нельзя перенести в её текущем статусе, например она уже отменена или завершена.

appointment-not-cancellable

409. Запись нельзя отменить в её текущем статусе, например она уже завершена.

service-inactive

409. Услугу этой записи выключили или удалили, поэтому запись нельзя перенести. Сама запись на месте: её можно прочитать и отменить. Чтобы перенести визит, включите услугу в личном кабинете или создайте запись на другую услугу.

invalid-duration

422. Для услуги с арендой времени duration_min меньше минимума, больше максимума или не попадает в шаг. Границы и шаг - в detail.

too-many-guests

422. Услуга с арендой (interval): гостей больше, чем max_guests услуги. У услуг fixed эта ошибка не приходит - лишние гости дают slot-unavailable.

starts-at-in-past

422. Время начала записи уже прошло.

service-not-found

422. Нет активной услуги с таким service_id, доступной ключу: услуги нет, она выключена или находится в проекте, которого нет в ключе.

branch-not-found

422. Среди активных филиалов проекта услуги нет филиала с таким branch_id, или у проекта вообще нет активных филиалов.

branch-id-required

422. У проекта несколько филиалов - укажите branch_id. Список филиалов отдаёт GET /v1/branches.

resource-not-eligible

422. Этот исполнитель не оказывает выбранную услугу или не работает в выбранном филиале.

contact-not-found

422. Клиента с таким contact_id нет в проекте услуги.

Диалоги

Длина текста сообщения зависит от канала: Telegram и ВКонтакте - до 4096 символов, MAX - до 4000, чат на сайте и почта - до 8000. Текст длиннее - ошибка 422 validation.

Если сообщение не удалось доставить клиенту, это не ошибка запроса. API отвечает 201, сообщение сохраняется со "status": "failed", а причина - в поле failure.code:

Повтор запроса с тем же Idempotency-Key вернёт то же сообщение со статусом failed. Чтобы отправить сообщение ещё раз, передайте новый ключ.

conversation-closed

409. Диалог закрыт или помечен как спам. API не открывает закрытые диалоги заново: ответьте из личного кабинета или дождитесь сообщения клиента - оно вернёт диалог в работу или начнёт новый.

conversation-archived

409. Диалог в чате на сайте завершён: посетитель сам начал новый диалог или диалог закрыли, а посетитель долго не возвращался. Сообщение до посетителя уже не дойдёт. Когда посетитель напишет снова, начнётся новый диалог - отвечайте в нём.

channel-not-supported

409. В канал этого диалога API не отправляет сообщения. Это диалоги продукта «Имидж» - комментарии в соцсетях: отвечать на них через API нельзя, читать и закрывать можно. Отправка работает в каналах web, telegram, vk, max и email.

channel-disconnected

409. Канал этого диалога отключили в личном кабинете, и отправить сообщение некуда. В этот диалог ответить уже нельзя - дождитесь, когда клиент напишет в подключённый канал.