Ошибки

Partner API использует стандартные коды состояния HTTP и тела ответов в формате JSON, чтобы объяснить причину неудачного запроса.

Структура ответа с ошибкой

Большинство ошибок API возвращают тело JSON с сообщением и, если доступно, структурированными подробностями.

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

Некоторые предметные конечные точки возвращают явное состояние и причину. Например, ошибки контроля доступа содержат такие поля, как reason, door_id, facility_id и event_id.

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

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

400 Bad Request

Запрос сформирован неправильно или в нем отсутствуют обязательные поля. Исправьте запрос, прежде чем повторять попытку.

401 Unauthorized

Ошибка аутентификации. Убедитесь, что вы используете HTTP Basic Auth с секретным ключом API в качестве имени пользователя и пустым паролем.

403 Forbidden

Ключ действителен, но операция не разрешена. Распространенные причины: использование ключа только для чтения для операции записи или попытка доступа к объекту, для которого ваша интеграция не включена.

404 Not Found

Запрошенный ресурс не найден или недоступен вашей интеграции.

409 Conflict

Запрос конфликтует с текущим состоянием ресурса. В контексте контроля доступа это может означать, что контроллер Door/Gate Controller находится в режиме обслуживания.

422 Unprocessable Entity

Запрос содержит допустимый JSON, но не проходит семантическую проверку. Исправьте данные, прежде чем повторять попытку.

429 Too Many Requests

Интеграция превысила документированное ограничение частоты запросов. Повторите попытку с экспоненциальной задержкой.

500 Internal Server Error

Performance Hub не удалось выполнить запрос из-за внутренней ошибки. Повторите попытку с задержкой. Если проблема не исчезнет, обратитесь в службу поддержки, указав конечную точку, метку времени и тело ответа.

503 Service Unavailable

Зависимая служба или устройство недоступны. При разблокировке контроллера Door/Gate Controller это может означать, что контроллер не в сети.

504 Gateway Timeout

Истекло время ожидания операции. При разблокировке контроллера Door/Gate Controller это означает, что разблокировка не была подтверждена до истечения времени ожидания.

Ошибки Access Time Windows

Проверка окон завершается ошибкой до того, как недопустимый снимок будет записан. Распространенные причины, при которых повторная попытка не поможет:

Отсутствует access_time_windows_revision, хотя указан access_time_windows.
Строковые значения, значения с плавающей запятой или значения эпохи, вероятно указанные в миллисекундах.
Недопустимый часовой пояс IANA, перевернутый интервал, повторяющийся external_id, пересекающиеся еженедельные блоки или неразделенный ночной блок.
Значение, выходящее за документированные ограничения по количеству, длине или продолжительности.

Повторная ревизия с другим нормализованным содержимым приводит к ошибке 409 Conflict. Выполните сверку с последним состоянием основного источника и назначьте более новую ревизию; не повторяйте попытки с конфликтующей парой. Более старая ревизия регистрируется как устаревший пропущенный снимок и не может перезаписать более новое состояние. Неизвестный или несопоставленный scope_key приводит к отказу в авторизации и должен рассматриваться как оповещение о проблеме конфигурации.

Если при доставке истекло время ожидания или получена временная ошибка 5xx, повторите отправку точно того же нормализованного снимка с той же ревизией. Если не удалось получить данные из вышестоящего источника, полностью опустите поле окон; никогда не подставляйте пустой массив.

Сведения для службы поддержки

При обращении в службу поддержки укажите:

Конечную точку и метод HTTP.
Время и часовой пояс.
Идентификатор ключа партнера (не сам секретный ключ).
Использованный идентификатор объекта.
Идентификатор исходной записи в вашей системе.
Состояние и тело ответа.
event_id или command_id, если доступны.