Центр поддержкиИнтеграции

Для: Администраторы

Обработка ошибок и кодов состояния API.

Прочитайте текст ошибки, что означают коды 400, 401, 403, 404, 500 и 503, и почему элемент, который ваш ключ не видит, выдает ошибку 404.

В этой статье5 разделов

На этой странице рассматривается способ описания ситуации, когда звонок отклоняется, как для управляющей ключи, так и для хабовых ключей.

Тело ошибки

Каждая отклоненная звонок соответствует определенному статус-коду и JSON-образу информации.

{
  "error": {
    "code": 400,
    "message": "CaseReferenceIdExistsException",
    "error_type": "ClientException",
    "reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
  }
}
ПолеЧто в нём содержится
codeСнова код статуса.
messageНазвание ошибки – например, CaseReferenceIdExistsException. Пусть ваш код будет работать с этим значением; оно не меняется в зависимости от языка, на котором написан код.
error_typeВид ошибки: ClientException – при отказе; ApiException – при некорректном запросе; SessionException – при отсутствии необходимого ключа; ModelException – при отказе в обработке определенного ключа или при отказе со стороны базы данных; TransientException – при небольших проблемах, которые можно исправить путем повторной попытки; InternalError – при возникновении ошибок в процессе работы CaseActive.
reasonЕсли есть какие-либо детали, то это могут быть идентификаторы несовместимых записей, или проблемы с первым полем данных. Часто эти поля пусты.
errorsДля некорректных запросов необходимо указать только один элемент для каждого поля.

Полевые ошибки

Запрос, в котором отсутствуют или некорректно указаны поля, считается некорректным и возвращается со статусом 400. SchemaFieldsException, Вместе с… errors Заполнение каждой поля. location Называется поле; точки используются для обозначения того, что одно поле находится внутри другого. message Называем проблему так:

{
  "error": {
    "code": 400,
    "message": "SchemaFieldsException",
    "error_type": "ApiException",
    "reason": "FieldRequiredException",
    "errors": [
      {"domain": "json", "location": "ref_id", "locationId": "ref_id", "locationType": "schema", "message": "FieldRequiredException", "reason": "FieldRequiredException"}
    ]
  }
}

domain соответствует json для параметров тела, а query — для параметров адреса. Распространенные ошибки в полях:

messageВ чем дело
FieldRequiredExceptionЕго нет, или же там, где его не должно быть, пустое место.
FieldValidatorFailedExceptionЕго значение не является одним из допустимых значений. Например, это может быть роль, тип случая или этап, которого у вашего хаба нет.
FieldMinLengthException, FieldMaxLengthExceptionЭто слишком коротко или слишком длинно.
FieldLimitTooLargeExceptionСписок с элементами limit имеет более 1000 элементов. Это самый большой объем информации, который может содержать одна страница.
FieldEmailTypeException, FieldPhoneTypeExceptionНе адрес электронной почты, не номер телефона с кодом страны.
FieldNameTypeExceptionИмя, которое не может содержать всех необходимых символов.
FieldPathSlugTypeExceptionID или референс-ID, содержащий символы, отличные от букв, цифр, тире и штампов.
FieldDateTypeExceptionНе дата, например 2026-03-15

Те поля API, которые неизвестны, игнорируются, а не отклоняются. Поэтому убедитесь в правильности написания этих полей по сравнению с описанием, приведенным в документации.

Коды состояния

СтатусЧто это значитЧто делать
400Запрос некорректен, или изменения не допускаются. Это может быть ошибка в форматировании поля, или возникла какая-либо препятствующая процедуре изменений причина, указанная в message. Например: CaseReferenceIdExistsExceptionИсправьте ошибки перед тем, как снова отправить документ.
401Сам ключ был отклонен. См. раздел Аутентификация запросов API с использованием ключа.Стойте и проверьте ключ.
403Ключ может не сработать в таких случаях: вызов управляющего ключа не может привести к каким-либо результатам (BotNotAllowedException); заблокированный хаб (ManageBillingInactiveException для управляющего ключа, BillingReadOnlyException для ключа хаба после того, как портал становится односторонне доступным); закрытый случай (CaseClosedException); или изменения, которые противоречат другим изменениям, произведенным в тот же момент (ItemUpdateFailedException и другие).Необходимо выявить причину проблемы. Если произошел конфликт, повторите процедуру обработки данных и попробуйте снова.
404Этот элемент не существует. Он принадлежит другому хабу, либо удаляется. Кроме того, ваш ключ не может обнаружить этот элемент.Проверьте удостоверение личности.
500InternalError: Недостаток в функции CaseActive. Разработчикам необходимо это исправить.Попробуйте снова позже. Если проблема продолжается, обратитесь в службу поддержки.
503TransientException: В тот момент хаб был слишком занят.Попробуйте снова через некоторое время. Чем дольше будет ожидание, тем лучше.

Звонок, длительность которого превышает 30 секунд, прерывается с помощью сообщения типа 504 от сети, перед API. В таких случаях импорты избегают этой проблемы, работая в фоновом режиме.

Почему существует предмет, о существовании которого вы знаете? Ответ на вопрос 404.

Ключ “hub” выполняет функцию центра управления вашего устройства. Виртуальный помощникВиртуальный помощник Автоматизированный член команды, который публикует приветственные сообщения, проводит проверки и организует публикации для компании; его публикации отмечены значком виртуального помощника., Программа-ассистент видит только то, что может увидеть сама роль ассистента. Элементы, которые не видны в рамках этой роли, отвечают на запрос с кодом 404 – это значит, что такой элемент просто не существует. Следовательно, API не может обработать такие запросы. Для редактирования или удаления опубликованных счетов-фактур, а также для редактирования электронных документов, которые не видны в рамках этой роли, все равно возникает код 403. PublishAlreadyPublishedException. В списках некоторые элементы пропускаются без каких-либо объяснений. Чтобы узнать, какова роль этого элемента в списке, необходимо прочитать соответствующую информацию. role::bots С ключом управления; см. Читайте роли с использованием ключа управления..

Можно повторить попытку.

  • 503, а также любые значения типа TransientException – после небольшого ожидания.
  • 400 TransactionCanceledException – это количество элементов, которые возникают в результате некоторой активности. А CaseUserLimitOrTransactionException указывает на то, что после проверки объем элементов не является полным.
  • 500… Чуть позже.

Не пытайтесь снова использовать другие коды ответов типа 400, 401, 403 или 404. Их снова отклонит система.

Статьи по теме

Аутентификация API-запросов с помощью ключа.Отправьте свой ключ в виде токена носителя в API панели администратора для управления ключом или в API портала для ключа хаба, ограничив его использование только вашими IP-адресами.ИнтеграцииРазберитесь, что может делать API.Узнайте, к чему могут иметь доступ ключ управления и ключ концентратора, почему каждый ключ действует как виртуальный помощник и где находится полный технический паспорт.Интеграции