Performance Hub 로고Performance Hub
사이트 섹션: 개발자 및 파트너 리소스

오류

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

인증에 실패했습니다. API 비밀 키를 사용자 이름으로, 비밀번호를 빈 값으로 하여 HTTP Basic Auth를 사용하고 있는지 확인하십시오.

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 Window 실패

시간 창 유효성 검사는 잘못된 스냅샷이 기록되기 전에 실패합니다. 재시도할 수 없는 일반적인 원인은 다음과 같습니다.

  • access_time_windows가 있는데 access_time_windows_revision이 누락된 경우.
  • 문자열, 부동 소수점 또는 밀리초로 보이는 epoch 값.
  • 잘못된 IANA 시간대, 역전된 구간, 중복된 external_id, 겹치는 주간 블록 또는 분할되지 않은 야간 블록.
  • 문서화된 개수, 길이 또는 기간 제한을 벗어난 값.

같은 리비전을 다른 정규화 콘텐츠로 반복하면 409 Conflict가 발생합니다. 최신의 신뢰할 수 있는 상태와 조정한 후 더 새로운 리비전을 할당하십시오. 충돌하는 쌍을 계속 재시도하지 마십시오. 이전 리비전은 더 새로운 상태를 덮어쓰지 않고 건너뛴 오래된 스냅샷으로 보고됩니다. 알 수 없거나 매핑되지 않은 scope_key는 권한 부여에서 거부 방향으로 실패하며, 구성 알림으로 취급해야 합니다.

전송 시간이 초과되거나 일시적인 5xx를 받으면 정확히 같은 정규화 스냅샷을 같은 리비전으로 재시도하십시오. 업스트림 원본 조회에 실패한 경우에는 시간 창 필드를 완전히 생략하십시오. 절대 빈 배열로 대체하지 마십시오.

재시도 지침

다음은 제한된 지수 백오프로 재시도하십시오.

  • 429
  • 500
  • 502
  • 503
  • 504

다음은 무작정 재시도하지 마십시오.

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

출입 통제의 경우 자체 출입 규칙과 안전 프로세스에서 달리 정하지 않는 한 제한 시간 초과 및 오프라인 응답을 항상 잠금 해제 실패로 처리하십시오.

지원 요청 시 포함할 세부 정보

지원팀에 문의할 때 다음을 포함하십시오.

  • 엔드포인트 및 HTTP 메서드.
  • 타임스탬프 및 시간대.
  • 비밀 키가 아닌 파트너 키 ID.
  • 사용한 시설 식별자.
  • 귀사 시스템의 원본 레코드 ID.
  • 응답 상태 및 본문.
  • 가능한 경우 event_id 또는 command_id.