Skip to main content

Error Handling and Reporting

This section describes the most common errors that can occur while using the Digital Connect API services. This includes system errors and any mistakes an agent or passenger can make when managing reservations. Each error handling scenario is accompanied by appropriate code examples.

Some of the errors are a result of an invalid API usage, most commonly a missing mandatory key in the request or invalid value type. In such cases we recommend verifying the request against the API documentation before reporting a ticket to Sabre Customer Care.

How to Handle API Session Expiry

When a service is called with a non-existent or expired execution ID, or the session has expired (conversation that we have attempted to access was not found), the application will return below error message:

{
"status": "NotProcessed",
"type": "Application",
"errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST”
"timeStamp": "2015-12-05T21:59:11",
"message": "conversation '<id>' was completed or doesn't exist”
}

In case of such error, the solution is to start the flow from the beginning and to create a new conversation.

Error Reporting

When you send requests to and get responses from the API, you might encounter two types of API errors:

  • User errors: User errors are indicated by a 4xx HTTP response Digital Connect code. These errors indicate Digital Connect API Gateway found a problem with the user request, such as an authentication failure or missing required parameters. Fix the issue in the user application before submitting the request again.
  • Server errors: Server errors are indicated by a 5xx HTTP response code. These are generic errors that do not have specific handling. In most cases the solution is to resend the exact same request that triggered the wrong response and receive the correct one.

For each API error, Digital Connect API Gateway returns the following values:

  • A HTTP status code. For example: 400
  • An error code. For example: ERR.SSW.INTERNAL_ERROR
  • Status - the possible status codes are CompleteIncompleteNotProcessed and Unknown
  • An error type - the error types are: TransportValidationApplication and BusinessLogic. Currently, the application does not return an error message for Transport errors because Transport errors are mostly used for 2SG errors.
  • An error message. For example: Service is disabled in configuration.

For a list of error codes that Digital Connect API Gateway returns for client and server errors, refer to an overview section for each JSON service.

Error Message Formats

If an API call fails, an error message is returned. Errors are always structured as follows:

{
"status": "<status>",
"type": "<type>",
"errorCode": "<errorCode>”
"timeStamp": "2015-12-05T21:59:11",
"message": "<messageText>”
“details” :
{
      “<messageDetails>”
}
}

Error Message Examples

The following is an example of an actual error message with values. The “type” line indicates the type of error message. In this example, the error message type is Validation. The “details” area shows the field that failed validation, cabinClass, and the specific failure, invalid.format.

{
"status": "NotProcessed",
"type": "Validation",
"errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST”
"timeStamp": "2015-12-05T21:59:11",
"message": "Validation error”
“details” :
{
      “cabinClass”: [  
           “invalid.format”
           ]
}
}

If a request results in multiple validation failures, it is reported like the next example. This example shows multiple errors on multiple fields of the passenger details data. Each error shows the field and error detail. Note the use of the passenger index to identify which passenger in the booking each of the errors applies to.

{
"status": "NotProcessed",
"type": "Validation",
"errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST”
"timeStamp": "2015-12-05T21:59:11",
"message": "Validation error”
“details” :
{
  "passengers[0].passengerDetails.lastName": [
    "validation.text.tooLong"
  ],
  "passengers[0].passengerDetails.prefix": [
    "validation.error.not_valid"
  ],
  "passengers[0].passengerDetails.firstName": [
    "validation.text.tooLong"
  ],
  "passengers[1].passengerDetails.firstName": [
    "validation.text.tooLong"
  ]
}
}

Any error that results from the passed value not matching an AllowedValue statement will end validation and return the error.

In the case of multiple errors, other than an AllowedValue error, validation continues until all fields have been validated and multiple errors are returned as shown above.

Notes  

  • The error code is typically not a message that can be displayed directly to passengers; the airline needs to substitute message text of its own for display.
  • The formats for some basic data types are consistent across the Digital Connect services. Date should be in the format YYYY-MM-DD. Other data formats, such as Frequent Flyer account number format(s) are defined per Airline.

 

Multiple Error Messages per Field

In Digital Connect error messages from all the validators applied to a given field are returned.

Examples:

  • one validation error per field
    {
      "status": "NotProcessed",
      "type": "Validation",
      "errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST",
      "timeStamp": "2018-02-28T10:46:17",
      "message": "Validation error.",
      "details": {
        "origin": [
          "validation.field.invalid"
        ],
        "destination": [
          "validation.field.required"
        ]
      }
    }
  • multiple error messages per field
    {
      "status": "NotProcessed",
      "type": "Validation",
      "errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST",
      "timeStamp": "2018-02-28T10:46:17",
      "message": "Validation error.",
      "details": {
        "origin": [
          "validation.text.tooShort",
          "validation.field.invalid"
        ],
        "destination": [
          "validation.text.tooLong",
          "validation.field.invalid"
        ]
      }
    }

Common errors and suggested actions

In this section, you'll find common JSON errors and a suggested actions you might take to handle it.

4xx: Client Error Scenarios

This category of error status codes points out invalid/wrong client requests.

400 (Bad Request):

When the service was called with a non-existent or expired execution id, or the session has expired (conversation that the client has attempted to access was not found), the application returns below error message:

{
"status": "NotProcessed",
"type": "Application",
"errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST”
"timeStamp": "2015-12-05T21:59:11",
"message": "conversation '<id>' was completed or doesn't exist”
}

In case of such error, please start the flow from the beginning and create a new conversation.

400 (Bad Request):

That error means that a required field or parameter has not been provided by the client, the supplied value is invalid, or the combination of provided fields is invalid. Further details specifying can be found in the "details" section of the returned error:

{
  "status": "NotProcessed",
  "type": "Validation",
  "errorCode": "ERR.SSW.CLIENT.INVALID_REQUEST",
  "timeStamp": "2016-09-15T20:07:06",
  "message": "Validation error",
  "details": {
    "itineraryParts": [
      "validation.error.required_but_not_found"
    ]
  }
}

In case of such error, please check the parameters sent in the request (if all required fields have been sent and if all parameters specified in the request fit the permissible range or allowed values).

400 (Bad Request):

JSON request could not be mapped properly e.g. due to an invalid name of a field.

Specified field is invalid:

  • The user has provided subfields for field that does not refer to subobject(s);
  • The user has omitted subfields that were required,
  • The request could not be understood by the server due to malformed syntax. (no closing quote, missing curly brackets, date is not a date e.g. 2015-13-13 etc.).
{
"status": "NotProcessed",
"type": "Validation",
"errorCode": " ERR.SSW.CLIENT.JSON_MAPPING_ERROR”
"timeStamp": "2015-12-05T21:59:11",
"message": " Json Mapping Error”
}

5xx: Server Error Scenarios

The server is responsible for these error status codes.

A 500 type error is not the client’s fault. Those are generic errors that do not have specific handling. In most cases the solution for it is to resend the exact same request that triggered the wrong response and receive the correct one.

500 ERR.SSW.INTERNAL_ERROR

Generic error code without well-defined business case.

Digital Connect is not able to return specific error code for the reason of error in this business scenario; for example: The service was unable to complete the request, possible due to a failure in a downline system.

{
"status": "Incomplete",
"type": "Application",
"errorCode": "ERR.SSW.INTERNAL_ERROR”
"timeStamp": "2015-12-05T21:59:11",
"message": "<message>”
}

500 ERR.SSW.APP.TECHNICAL_ERROR

Digital Connect has encountered an unexpected technical error while processing the request.

{
"status": "Unknown",
"type": "Application",
"errorCode": " ERR.SSW.APP.TECHNICAL_ERROR”
"timeStamp": "2015-12-05T21:59:11",
"message": "Technical error during processing the request”
}

503 ERR.SSW.INTERNAL.SERVICE_UNAVAILABLE

Digital Connect Service is unavailable by the following reasons:

  • Service is disabled by the configuration
  • Server downtime occurred
  • Downline system is unavailable/timed out for unknown reason

 

{
"status": "Incomplete",
"type": "Application",
"errorCode": " ERR.SSW.INTERNAL.SERVICE_UNAVAILABLE”
"timeStamp": "2015-12-05T21:59:11",
"message": " Service is disabled in configuration.”
}
{
"status": "Incomplete",
"type": "Application",
"errorCode": " ERR.SSW.INTERNAL.SERVICE_UNAVAILABLE”
"timeStamp": "2015-12-05T21:59:11",
"message": " Technical issue”
}