Errors

The Partner API uses standard HTTP status codes and JSON response bodies to explain why a request failed.

Error response shape

Most API errors return a JSON body with a message and, where available, structured details.

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

Some domain-specific endpoints return an explicit status and reason. For example, access-control failures include fields such as reason, door_id, facility_id, and event_id.

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

Status codes

400 Bad Request

The request is malformed or missing required fields. Fix the request before retrying.

401 Unauthorized

Authentication failed. Check that you are using HTTP Basic Auth with your API secret key as the username and an empty password.

403 Forbidden

The key is valid but the operation is not allowed. Common causes include using a read-only key for a write operation or attempting to access a facility where your integration is not enabled.

404 Not Found

The requested resource was not found or is not available to your integration.

409 Conflict

The request conflicts with the current resource state. For access control, this can include a Door/Gate Controller being in maintenance mode.

422 Unprocessable Entity

The request is valid JSON but fails semantic validation. Fix the data before retrying.

429 Too Many Requests

The integration exceeded the documented rate limit. Retry with exponential backoff.

500 Internal Server Error

Performance Hub could not complete the request because of an internal error. Retry with backoff. If the problem continues, contact support with the endpoint, timestamp, and response body.

503 Service Unavailable

A dependent service or device is unavailable. For Door/Gate Controller unlocks, this can mean the controller is offline.

504 Gateway Timeout

The operation timed out. For Door/Gate Controller unlocks, this means the unlock was not confirmed before the timeout window.

Access Time Window failures

Window validation fails before the invalid snapshot is written. Common non-retryable causes include:

• Missing access_time_windows_revision when access_time_windows is present.
• String, floating-point, or likely-millisecond epoch values.
• An invalid IANA timezone, inverted interval, duplicate external_id, overlapping weekly blocks, or an overnight block that was not split.
• A value outside documented count, length, or span limits.

A repeated revision with different normalized content is a 409 Conflict. Reconcile against the latest authoritative state and allocate a newer revision; do not keep retrying the conflicting pair. An older revision is reported as a stale skipped snapshot rather than allowed to overwrite newer state. An unknown or unmapped scope_key fails closed for authorization and should be treated as a configuration alert.

If delivery times out or receives a transient 5xx, retry the exact normalized snapshot with the same revision. If the upstream source fetch failed, omit the window field entirely; never substitute an empty array.

Retry guidance

Retry these with bounded exponential backoff:

• 429
• 500
• 502
• 503
• 504

Do not blindly retry these:

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

For access control, always treat timeout and offline responses as failed unlocks unless your own access rules and safety processes say otherwise.

Support details to include

When contacting support, include:

• Endpoint and HTTP method.
• Timestamp and timezone.
• Partner key ID, not the secret key.
• Facility identifier used.
• Source record ID from your system.
• Response status and body.
• event_id or command_id where available.