Docs

Errors ​

Errors occur even in the best of systems and we try and always provide sensible error codes which will help you handle the error properly. All errors that you encounter in the All Aboard API will be GraphQL errors, optionally with an extensions property.

Extensions ​

Extensions is a GraphQL feature which allows us to add additional information to the error response. This is where we add the error code and any additional information which can help you identify the cause of the error.

json
{
  "errors": [
    {
      "message": "Message describing what went wrong",
      "locations": [{ "line": 6, "column": 7 }],
      "path": ["node", "field", 1, "name"],
      "extensions": {
        "code": "ERROR_CODE",
        "args": {
          "name": "value"
        }
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "Message describing what went wrong",
      "locations": [{ "line": 6, "column": 7 }],
      "path": ["node", "field", 1, "name"],
      "extensions": {
        "code": "ERROR_CODE",
        "args": {
          "name": "value"
        }
      }
    }
  ]
}

Error codes ​

Working with many data and ticketing provders means that we have to handle a lot of different error codes from several systems, sometimes dependent on each other. We try and map these to a common set of error codes which are listed below.

UNKNOWN ​

This can happen either when creating a booking or when prebooking tickets which happens when creating an order or a payment. This error code is used when we encounter an upstream error from one of our ticketing providers and the error is not recognized or when the error is not related to the booking or prebooking.

json
{
  "errors": [
    {
      "message": "Unable to process booking",
      "extensions": {
        "code": "UNKNOWN"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "Unable to process booking",
      "extensions": {
        "code": "UNKNOWN"
      }
    }
  ]
}

UNAUTHORIZED ​

This happens when Authorization header is missing or the provided API key is invalid.

json
{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ]
}

UNKNOWN_NODE_ID ​

This happens when you try to fetch a node by ID which does not exist.

json
{
  "errors": [
    {
      "message": "Unknown node id",
      "extensions": {
        "code": "UNKNOWN_NODE_ID"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "Unknown node id",
      "extensions": {
        "code": "UNKNOWN_NODE_ID"
      }
    }
  ]
}

VALIDATION_ERROR ​

When working with Bookings the input data is validated and may fail validation. This error code is used when the input data is invalid. The extensions.args.validation property will contain the validation rule that failed.

You can use the path property to determine which field failed validation.

json
{
  "errors": [
    {
      "message": "Passenger date of bith is required",
      "path": ["updateBooking", "passengers", 1, "dateOfBirth"],
      "extensions": {
        "code": "VALIDATION_ERROR",
        "args": {
          "validation": "required"
        }
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "Passenger date of bith is required",
      "path": ["updateBooking", "passengers", 1, "dateOfBirth"],
      "extensions": {
        "code": "VALIDATION_ERROR",
        "args": {
          "validation": "required"
        }
      }
    }
  ]
}

NO_TICKETS ​

Tickets may sell out between the time you select a journey and the time you create a booking. This error code is used when one or more of the selected tickets are no longer available. In that case you should request a new JourneyOffer before trying to create a booking again.

You can use the extensions.args.originName and extensions.args.destinationName to determine which tickets are no longer available.

json
{
  "errors": [
    {
      "message": "One of the selected tickets are no longer available",
      "extensions": {
        "code": "NO_TICKETS",
        "args": {
          "originName": "London",
          "destinationName": "Paris"
        }
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "One of the selected tickets are no longer available",
      "extensions": {
        "code": "NO_TICKETS",
        "args": {
          "originName": "London",
          "destinationName": "Paris"
        }
      }
    }
  ]
}

COMPARTMENT_TYPE_UNAVAILABLE ​

The selected compartment type is not available for the selected journey. This error code is used when the selected compartment type is not available for the selected journey. In that case you should request a new JourneyOffer before trying to create a booking again.

json
{
  "errors": [
    {
      "message": "The selected compartment type is not available",
      "extensions": {
        "code": "COMPARTMENT_TYPE_UNAVAILABLE"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "The selected compartment type is not available",
      "extensions": {
        "code": "COMPARTMENT_TYPE_UNAVAILABLE"
      }
    }
  ]
}

BOOKING_ALREADY_USED ​

Due to technical limitations with certain ticketing providers, some bookings (depnending on the underlying carreir) can only be used once. This means that if you try to create an order or a payment which then fails or the payment is cancelled, the booking cannot be reused to perform the same action again. In that case you should create a new booking and try again.

json
{
  "errors": [
    {
      "message": "This booking cannot be used again",
      "extensions": {
        "code": "BOOKING_ALREADY_USED"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "This booking cannot be used again",
      "extensions": {
        "code": "BOOKING_ALREADY_USED"
      }
    }
  ]
}

OUTSIDE_TIMETABLE ​

Just like with ticket availability, operators release new timetables at different intervals. Most often this happens around the end of the year when both booking horizons and timetable availability may be shorter than usual.

json
{
  "errors": [
    {
      "message": "The timetable for the given date is not available yet",
      "extensions": {
        "code": "OUTSIDE_TIMETABLE"
      }
    }
  ]
}
{
  "errors": [
    {
      "message": "The timetable for the given date is not available yet",
      "extensions": {
        "code": "OUTSIDE_TIMETABLE"
      }
    }
  ]
}