Error handling
The Lodging Partner GraphQL API responses can contain errors that occur during the different phases of a request (authentication, validation, schema generation, and execution) as well as internal system errors. The following describes the payload of an HTTP GraphQL response:
1{2 data: { ... },3 errors: [] // only present if an error occurs4}
The semantics of the response format as well as more details about the error object content (returned in the errors
array) are described in full detail in the GraphQL error spec.
HTTP status codes
These status codes are used in response to the HTTP request:
Code | Description |
---|---|
200 | HTTP request was successful. However, GraphQL execution errors are reported using this status code. The response will include a JSON response payload that follows the error format described below. |
400 | Server cannot process the request because of an issue with the request. The response will include a JSON response payload that follows the error format described below. |
401 | Unauthorized. The API cannot fulfill the request because the client does not have the necessary scopes to access the capability or because the access token is missing, invalid, or expired. Response does not contain a response body. |
403 | Forbidden. The server refuses to authorize it because the partner does not have the necessary scopes to call the specific capability, is not allowed to access a specific resource (permission check error), or is not allowed to upload/download the files. The response will include a JSON response payload that follows the error format described below. |
404 | Not found. The requested file could not be found. The response will include a JSON response payload that indicates the file ID. |
429 | User has sent too many requests in a given amount of time ("rate limiting"). Response does not contain a response body. |
500 | An internal error occurred. Response may contain a JSON response payload depending on the type of error or where it originates in the application stack. |
Error classes
If an error is thrown before or during the following, it is associated with the GraphQL request:
- transport of the HTTP request to the server hosting the GraphQL endpoint
- the request phase of the GraphQL lifecycle
- the parse phase of the GraphQL lifecycle
- the validate phase of the GraphQL lifecycle
If an error is during the execute phase of the GraphQL lifecycle, it is associated with the GraphQL execution.
In either case, an error object is returned to the requester. An HTTP or GraphQL request error results in a non-200 status code, while a GraphQL execution error results in a 200 status code. These error classes are defined as follows:
User input error during GraphQL execution
This occurs when an input or parameter to a resolver was not in an expected form or did meet parameter requirements. The intention of this type of error is to give the user information about what to change or provide. An HTTP status code of 200 is returned. User input messages include the following:
Invalid value in 'name'. Permissible values are BASIC_PROMOTION, EARLY_BOOKING_PROMOTION, MULTI_NIGHT_PROMOTION or SAME_DAY_PROMOTION.
Invalid value provided for minLengthOfStay. Permissible values are between 1 and 28.
Invalid value provided for maxLengthOfStay. Permissible values are between 1 and 28.
The maxLengthOfStay cannot be lesser than the minLengthOfStay.
For SAME_DAY_PROMOTIONS, min and max Advance Booking Days should have the value 0.
The bookingLocalDateTimeTo cannot be before the bookingLocalDateTimeFrom.
The travelDateTo cannot be before the travelDateFrom.
The travelDateFrom cannot be before the bookingLocalDateTimeFrom.
The travelDateTo cannot be before the bookingLocalDateTimeTo.
The travelDateTo cannot be after max purchase date.
For SAME_DAY_PROMOTION, the book and stay date ranges should be the same.
'sameDayBookingStartTime' field requires a value when creating a SAME_DAY_PROMOTION.
'sameDayBookingStartTime' can only be specified for SAME_DAY_PROMOTION
For SAME_DAY_PROMOTION, DAY_OF_WEEK_DISCOUNT type cannot be specified. Only SINGLE_DISCOUNT is supported.
For SAME_DAY_PROMOTION, MULTI_NIGHT_DISCOUNT type cannot be specified. Only SINGLE_DISCOUNT is supported.
When discount unit is percentage, the value can only be between 1 and 75.
For DAY_OF_WEEK discount type, at least one day of "monday, tuesday, wednesday, thursday, friday, saturday or sunday should have a value more than 0.
For DAY_OF_WEEK discount type, values cannot be less than 0.
memberOnlyAdditionalValue cannot be specified when isMemberOnly is set to true.
Cannot include memberOnlyAdditionalValue with promotion id: %s.
Cannot include memberOnlyAdditionalValue with SAME_DAY_PROMOTION.
Invalid value provided for minAdvanceBookingDays. Permissible values are between 0 and 500.
Invalid value provided for maxAdvanceBookingDays. Permissible values are between 0 and 500.
The maxAdvanceBookingDays cannot be lesser than the minAdvanceBookingDays.
For MULTI NIGHT discount type, applicableNight can only be between 2 and 28.
For MULTI NIGHT discount type, minLengthOfStay cannot be less than applicableNight.
For MULTI NIGHT discount type, cannot include memberOnlyAdditionalValue when value is 100.
For MULTI NIGHT discount type, when discount unit is percentage, the value can be 100 or only be between 1 and 75.
For MULTI NIGHT discount type, when discount unit is percentage, the sum of the value and member only additional value can only be between 1 and 75.
When creating a multi-night promotion, ensure the promotion name is MULTI_NIGHT_PROMOTION.
The 'code' field contains invalid characters. Refer to API documentation for full list of invalid characters.
The 'code' field cannot be empty or whitespace.
The bookingLocalDateTimeTo cannot be before the bookingLocalDateTimeFrom.
At least one valid rateplan Id needs to be provided within 'eligibleRatePlans' argument.
eligibleRatePlans argument must consist of rateplans belonging to the property. The rateplanId(s) -%s - do not belong to property %s
MULTI_NIGHT_PROMOTION is not a supported name for single discounts. Supported names: BASIC_PROMOTION, SAME_DAY_PROMOTION, EARLY_BOOKING_PROMOTION
MULTI_NIGHT_PROMOTION is not a supported name for day of week discounts. Supported names: BASIC_PROMOTION, EARLY_BOOKING_PROMOTION.
Cannot update promotion name: %s to a SAME_DAY_PROMOTION.
Cannot update promotion name: %s from a SAME_DAY_PROMOTION.
Cannot update promotion name: %s to a MULTI_NIGHT_PROMOTION.
Cannot update promotion name: %s from a MULTI_NIGHT_PROMOTION.
The travelDateFrom cannot be before the bookingLocalDateTimeFrom.
The travelDateTo cannot be before the bookingLocalDateTimeTo.
The travelDateFrom should be at least %1$1s days after bookingLocalDateTimeFrom since a minAdvanceBookingDays of %1$1s is specified.
The travelDateTo cannot be before the travelDateFrom.
Travel end date cannot be more than two years in the future.
%s cannot be set to null. Please update with a non-null value.
For SINGLE discount type, when discount unit is percentage, the value can only be between 1 and 75.
For SINGLE discount type, when discount unit is percentage, the sum of the value and member only additional value can only be between 1 and 75.
The promotion Id [%s] does not exist.
Promotion Id [%s] cannot be updated via the API because it is a contracted promotion.
One or more invalid IDs found in the list of eligible rate plans: xxxxxx. Make sure each ID represents an active rate plan.
One or more inactive IDs found in the list of eligible rate plans: xxxxxx. Make sure each ID represents an active rate plan.
- Duplicate IDs found in the list of eligible rate plans: xxxxxxxx. Make sure each ID appears only once in the list.
Here is an example of the error object response format:
1{2 "errors": [3 {4 "message": "Invalid value in 'name'. Permissible values are BASIC_PROMOTION, EARLY_BOOKING_PROMOTION or SAME_DAY_PROMOTION.",5 "locations": [],6 "path": [7 "reservationsByPropertyId"8 ],9 "extensions": {10 "code": "BAD_USER_INPUT"11 }12 }13 ],14 "data": {15 "property": {16 "reservations": null17 }18 },19 "extensions": {}20}
Data source does not exist
This type of error occurs when you are trying to access a resource that doesn't exist, such as if a property doesn't exist in our systems yet. An HTTP status code of 200 is returned. Here is an example of the error object response format:
1{2 "message": "id: PMSC/PM/396240 not found.",3 "locations": [4 {5 "line": 2,6 "column": 37 }8 ],9 "path": [10 "property"11 ],12 "extensions": {13 "code": "DATA_SOURCE_ERROR"14 }15}
Forbidden error during GraphQL execution
This type of error occurs when the requesting client is not permitted to access the requested resource or GraphQL data path. An HTTP status code of 403 is returned. Forbidden error messages include the following:
Insufficient Permissions
Missing Required Scope
Here is an example of the error object response format:
1{2 "errors": [3 {4 "message": "Insufficient Permissions on field=promotions for args={\"pageSize\":10,\"filter\":{\"status\":\"ACTIVE\"}}",5 "path": [6 "...",7 "promotions"8 ],9 "extensions": {10 "code": "FORBIDDEN"11 }12 }13 ],14 "data": {15 "property": null16 },17 "extensions": {18 "trace": {19 "Trace-ID": "d3d843da-92a8-4e5b-80dc-f13dd5c9d89d"20 }21 }
Syntax errors in the GraphQL request
These occur when the GraphQL operation payload in the GraphQL request is malformed. An HTTP status code of 400 is returned. Here is an example of the error object response format:
1{2 "message": "Syntax Error: Unexpected Name \"qury\"",3 "locations": [4 {5 "line": 1,6 "column": 17 }8 ],9 "extensions": {10 "code": "GRAPHQL_PARSE_FAILED"11 }12}
Validation errors in the GraphQL request
This type of error occurs when a query is syntactically valid but does not adhere to the restrictions defined by the schema, such as if a required argument was not provided. An HTTP status code of 200 is returned. Here is an example of the error object response format:
1{2 "message": "Field \"property\" argument \"propertyId\" of type \"ID!\" is required, but it was not provided.",3 "locations": [4 {5 "line": 2,6 "column": 37 }8 ],9 "extensions": {10 "code": "GRAPHQL_VALIDATION_FAILED"11 }12}
Unknown resource
If a non-existent resource is requested, such as an advertiser or property that does not exist, an HTTP status code of 200 is returned but the data set is null. Here is an example of the response:
1{2 "message": "an unexpected error occurred",3 "locations": [4 {5 "line": 2,6 "column": 37 }8 ],9 "path": [10 "property"11 ],12 "extensions": {13 "code": "INTERNAL_SERVER_ERROR"14 }15}
Internal server error during GraphQL execution
This type of error occurs when an error object is thrown from a resolver, when an error could not automatically be remapped to a known error class, or when an internal server error is thrown from a resolver. An HTTP status code of 200 is returned. Here is an example of the error object response format:
1{2 "message": "<message provided to error class constructor>",3 "locations": [4 {5 "line": 2,6 "column": 37 }8 ],10 "extensions": {11 "code": "INTERNAL_SERVER_ERROR"12 }13}