Troubleshooting Facilities API

This topic provides useful information to help you troubleshoot any errors you may encounter while implementing the Facilities API.

Missing required fields

The following error response indicates that an unsupported (unrecognized) field wrong_field was present in the request body.

{
  "errors": [
    {
      "message": "Invalid value",
      "code": 320,
      "details": {
        "fields": "instances.wrong_field",
        "facility_id": 2,
        "instance_id": null
      },
      "description": "Unrecognized field \"wrong_field\" (class com.booking.contentapi.facilitiesapi.models.api.Instance), not marked as ignorable"
    }
  ],
  "meta": {
    "ruid": "X-RUID-EXAMPLE"
  }
}

Most of the error descriptions will contain the fields object which can help you understand the exact field causing the issue.

Common errors

This section captures the common errors you may encounter while implementing the Facilities API.

Missing instance field

Error description: instances required for facility_id: {id}

You can encounter this error when you fail to include the instances array for a multi-instance facility.

{
  "errors": [
    {
      "message": "Invalid value",
      "code": 320,
      "details": {
        "fields": "property_facility_list[0]"
      },
      "description": "instances required for facility_id:2"
    }
  ],
  "meta": {
    "ruid": "f5197afa-4ec2-4236-89d1-b18ed4fda4f5"
  }
}

Invalid request example

For example, this is an invalid request:

[
  {
    "facility_id": 2,
    "state": "PRESENT"
  },
  ...
]

To fix the error, add the instances array.

Parking (Facility id: 2) is a multi-instance facility and requires the instances object.

Valid request example

[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 56327065,
        "parking_details": {
          "name": "Parking #1",
          "parking_type": "PARKING_GARAGE",
          "parking_location": "ON_SITE",
          "parking_access": "ONLY_GUESTS",
          "parking_reservation": "NEEDED",
          "max_height_m": 99.0,
          "has_valet_service": "PRESENT",
          "has_onsite_staff": "PRESENT",
          "has_gated_parking": "PRESENT",
          "has_security_cameras": "PRESENT",
          "has_ev_charging_station": "PRESENT",
          "has_accessible_parking_spots": "PRESENT"
        },
        "payment_details": {
          "charge_mode": "PAID",
          "charge_details": {
            "price": 100.0,
            "frequency": "PER_HOUR"
          }
        }
      }
    ],
    "state": "PRESENT"
  }
]

Missing required details object for multi-instance facilities

Error description: instances.{details_type} required for facility_id: {id}

You can encounter this error, if the required Details object was not specified for a multi-instance facility.

Invalid request example

For example, this is an invalid request.

[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 56327065,
        "payment_details": {
          "charge_mode": "PAID",
          "charge_details": {
            "price": 100.0,
            "frequency": "PER_HOUR"
          }
        }
      }
    ],
    "state": "PRESENT"
  }
]

For Parking (Facility id: 2), parking_details must be specified.

Valid request example

This is a valid request example.

[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 56327065,
        "parking_details": {
          "name": "Parking #1",
          "parking_type": "PARKING_GARAGE",
          "parking_location": "ON_SITE",
          "parking_access": "ONLY_GUESTS",
          "parking_reservation": "NEEDED",
          "max_height_m": 99.0,
          "has_valet_service": "PRESENT",
          "has_onsite_staff": "PRESENT",
          "has_gated_parking": "PRESENT",
          "has_security_cameras": "PRESENT",
          "has_ev_charging_station": "PRESENT",
          "has_accessible_parking_spots": "PRESENT"
        },
        "payment_details": {
          "charge_mode": "PAID",
          "charge_details": {
            "price": 100.0,
            "frequency": "PER_HOUR"
          }
        }
      }
    ],
    "state": "PRESENT"
  }
]

Missing required details

Error description: must not be null

{
  "errors": [
    {
      "message": "Invalid value",
      "code": 320,
      "details": {
        "fields": "property_facility_list[0].instances[0].parking_details.name"
      },
      "description": "must not be null"
    }
  ],
  "meta": {
    "ruid": "X-RUID-EXAMPLE"
  }
}

You can encounter this error, when you fail to include a required field for a multi-instance facility.

Invalid request example

For example, this is an invalid request.

[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 56327065,
        "parking_details": {
          "parking_type": "PARKING_GARAGE",
          "parking_location": "ON_SITE",
          "parking_access": "ONLY_GUESTS",
          "parking_reservation": "NEEDED",
          "max_height_m": 99.0,
          "has_valet_service": "PRESENT",
          "has_onsite_staff": "PRESENT",
          "has_gated_parking": "PRESENT",
          "has_security_cameras": "PRESENT",
          "has_ev_charging_station": "PRESENT",
          "has_accessible_parking_spots": "PRESENT"
        },
        "payment_details": {
          "charge_mode": "PAID",
          "charge_details": {
            "price": 100.0,
            "frequency": "PER_HOUR"
          }
        }
      }
    ],
    "state": "PRESENT"
  }
]

For Parking, parking_details.name field is mandatory.

Valid request example

{!code/facilities-api/valid_parking.json!}

Unique names for multi-instance facilities

Error description: name must be unique for instances in facility_id: {id}

You can encounter this error, if more than one instance of a multi-instance facility has the same name. Facilities with multiple instances must have unique names (unique per property, not absolute)

{
  "errors": [
    {
      "message": "Invalid value",
      "code": 320,
      "details": {
        "fields": "property_facility_list[0]"
      },
      "description": "name must be unique for instances in facility_id: 2"
    }
  ],
  "meta": {
    "ruid": "6dc95763-7ad3-4c76-9f88-e363f84a29f9"
  }
}

Invalid request example

The following is an invalid request example.

[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 56327065,
        "parking_details": {
          "name": "Parking #1",
          ...
        },
        "payment_details": {
          ...
        }
      },
      {
        "parking_details": {
          "name": "Parking #1",
          ...
        },
        ...
      }
    ],
    "state": "PRESENT"
  }
]

For Parking, the name field must be unique across all instances.

Valid request example

[
  {
    "facility_id": 2,
    "instances": [
      {
        "instance_id": 56327065,
        "parking_details": {
          "name": "Parking #1",
          ...
        },
        "payment_details": {
          ...
        }
      },
      {
        "parking_details": {
          "name": "Parking #2",
          ...
        },
        ...
      }
    ],
    "state": "PRESENT"
  }
]