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

認証に失敗しました。HTTP Basic 認証を使用し、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 やマッピングされていない scope_key は、認可の面で拒否側に倒れるため、設定に関するアラートとして扱ってください。

配信がタイムアウトした場合や一時的な 5xx を受信した場合は、正規化済みのスナップショットをそのまま同じリビジョンで再試行してください。上流のソースからの取得に失敗した場合は、ウィンドウのフィールド自体を省略してください。空の配列で代用しないでください。

再試行のガイダンス

次のエラーは、上限付きの指数バックオフで再試行してください。

  • 429
  • 500
  • 502
  • 503
  • 504

次のエラーは、むやみに再試行しないでください。

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

アクセスコントロールでは、独自のアクセスルールや安全手順で別途定めていない限り、タイムアウトやオフラインのレスポンスは常に解錠の失敗として扱ってください。

サポートに伝える詳細

サポートに連絡する際は、次の情報を含めてください。

  • エンドポイントと HTTP メソッド。
  • タイムスタンプとタイムゾーン。
  • パートナーキー ID（シークレットキーではありません）。
  • 使用した施設識別子。
  • お使いのシステムでのソースレコード ID。
  • レスポンスのステータスと本文。
  • 利用可能な場合は event_id または command_id。