错误

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

请求与资源的当前状态冲突。对于门禁控制，这可能包括门/闸机控制器处于维护模式。

422 Unprocessable Entity

请求是有效的 JSON，但未通过语义验证。请先修正数据再重试。

429 Too Many Requests

集成超出了文档所述的速率限制。请使用指数退避进行重试。

500 Internal Server Error

由于内部错误，Performance Hub 无法完成请求。请使用退避进行重试。如果问题仍然存在，请联系支持并提供端点、时间戳和响应正文。

503 Service Unavailable

某个依赖的服务或设备不可用。对于门/闸机控制器解锁，这可能表示控制器处于离线状态。

504 Gateway Timeout

操作超时。对于门/闸机控制器解锁，这表示在超时时间内未确认解锁。

Access Time Window 失败

时间窗口验证会在写入无效快照之前失败。常见的不可重试原因包括：

• 存在 access_time_windows 时缺少 access_time_windows_revision。
• 字符串、浮点数或疑似毫秒级的纪元时间值。
• 无效的 IANA 时区、颠倒的时间区间、重复的 external_id、重叠的每周时段，或未拆分的跨夜时段。
• 超出文档所述数量、长度或跨度限制的值。

重复的修订号但规范化内容不同时，返回 409 Conflict。请根据最新的权威状态进行对账并分配更新的修订号；不要继续重试存在冲突的组合。较旧的修订号会被报告为已跳过的过时快照，而不会覆盖较新的状态。未知或未映射的 scope_key 在授权时会按拒绝处理（fail closed），应将其视为配置警报。

如果投递超时或收到暂时性的 5xx，请使用相同的修订号重试完全相同的规范化快照。如果从上游源获取数据失败，请完全省略时间窗口字段；切勿以空数组代替。

重试指南

对以下错误使用有限次数的指数退避进行重试：

• 429
• 500
• 502
• 503
• 504

不要盲目重试以下错误：

• 400
• 401
• 403
• 404
• 409
• 422

对于门禁控制，除非您自己的访问规则和安全流程另有规定，否则请始终将超时和离线响应视为解锁失败。

联系支持时需提供的详细信息

联系支持时，请提供：

• 端点和 HTTP 方法。
• 时间戳和时区。
• 合作伙伴密钥 ID，而非密钥本身。
• 使用的设施标识符。
• 您系统中的源记录 ID。
• 响应状态和正文。
• event_id 或 command_id（如有）。