Errors

Duffel uses standard HTTP response codes to indicate the success or failure of API requests.

Status codes

Code	Reason	Description
200	OK	The request was successful
201	Created	The request was successful, and a new resource was created
204	No Content	The request was successful, but there is no response to send back
400	Bad Request	The request was invalid, for example due to missing headers
401	Unauthorized	An access token wasn't provided, or the provided token was invalid
403	Forbidden	A valid access token was provided, but it didn't have sufficient permissions
404	Not Found	The requested resource doesn't exist
406	Not Acceptable	The response type you requested with your `Accept` header isn't supported
422	Unprocessable Entity	A validation error occurred
429	Too Many Requests	You made too many requests to the API in a short period of time
500	Internal Server Error	Something went wrong. Please contact our support team and attach the `request_id` to your message. You should not retry this request.
502	Bad Gateway	Bad gateway error. Please contact our support team and attach the `request_id` to your message. You should not retry this request.
503	Service Unavailable	There is a temporary issue with the server. If the error persists please contact our support team and attach the `request_id` to your message. Please retry later.
504	Gateway Timeout	Gateway timeout error. If the error persists please contact our support team and attach the `request_id` to your message. Please retry later.

Errors

Error responses

Detailed information on what exactly went wrong will be included in the response body. Every error returned by the API includes:

Name	Description
`title`	A quick and simple description of what went wrong
`message`	A more detailed human-readable description of what went wrong
`documentation_url`	A URL pointing to a place in our documentation where you can read about the error
`type`	A machine-readable identifier for the general category of error
`code`	A machine-readable identifier for this specific error

Error types

An error’s type is an enum of the following values:

Name	Description
`authentication_error`	There was a problem with authenticating you - for example, you didn't provide an access token or it was invalid
`airline_error`	We've received an error back from the airline - for example, your booking has already been cancelled
`invalid_state_error`	You tried to perform an action on a resource that wasn't appropriate - for example, you tried to create an order with an offer that is no longer available
`rate_limit_error`	You made too many requests to the API in a short period of time
`validation_error`	You didn't provide a required parameter or a parameter you provided was invalid - for example, you didn't specify `slices` when creating an offer request
`invalid_request_error`	There was some other kind of problem with your request - for example, you requested a resource that doesn't exist or missed out a required header
`api_error`	Something went wrong on our side, and has been reported to us

Error codes

An error's code is an enum of the following values:

Value	Description
`access_token_not_found`	The access token used is not recognized by our system
`airline_internal`	The airline has responded with an internal error, please contact support
`airline_unknown`	The airline responded with an unexpected error, please contact support
`ancillary_service_not_available`	Requested ancillary service item(s) (e.g. seats) are no longer available, please update your requested services or create a new offer request
`already_cancelled`	The provided order has already been cancelled
`bad_request`	The request was unacceptable
`duplicate_booking`	A booking with the same details was already found for the selected itinerary, please select another offer
`duplicate_passenger_name`	The order cannot contain more than one passenger with the same name
`expired_access_token`	The provided access token has expired
`insufficient_balance`	There wasn't enough balance in the wallet for the operation - for example, you booked a flight for £300 with only £200 available in the wallet
`insufficient_permissions`	The provided token doesn't have sufficient permissions to perform the requested action
`internal_server_error`	There was something wrong on our end, please contact support
`invalid_authorization_header`	The `Authorization` header must conform to the following format: `Bearer API_TOKEN`
`invalid_content_type_header`	The `Content-Type` should be set to `application/json`
`invalid_data_param`	The data in the request body should be a JSON object
`invalid_email_address`	The airline does not support the format of the email address provided
`invalid_field_sets`	The request had an invalid combination of fields
`invalid_loyalty_card`	The airline did not recognise the loyalty programme account details for one or more of the passengers
`invalid_passenger_title`	The title of one of the passengers is not valid
`invalid_phone_number`	The phone number is not valid
`invalid_version_header`	The `Duffel-Version` header must be a known version of our API as indicated in our Docs
`malformed_data_param`	The data in the request body is not valid
`missing_authorization_header`	The `Authorization` header must be set and contain a valid API token
`missing_content_type_header`	The `Content-Type` header needs to be set to `application/json`
`missing_data_param`	The data in the request body should be nested under the `data` key
`missing_version_header`	The `Duffel-Version` header is required and must be a valid API version
`new_airline_initiated_change`	There is a new change to your order. Please try again later
`not_found`	The resource you are trying to access does not exist
`offer_expired`	The selected offer has already expired
`offer_no_longer_available`	The provided offer is no longer available, please select another offer or create a new offer request to get the latest availability
`offer_request_already_booked`	An offer from this offer request has already been booked; please perform a new search
`order_change_already_actioned`	The order change has already been actioned and cannot be actioned again
`order_creation_already_attempted`	Order creation has already been attempted for the provided offer. You should not retry this request.
`order_not_created`	The request to create an order was not successful. You should not retry this request.
`payment_amount_does_not_match_order_amount`	The `amount` provided in the payment does not match the `total_amount` of the order
`payment_currency_does_not_match_order_currency`	The `currency` provided in the payment does not match the `total_currency` of the order
`price_changed`	The provided offer is no longer available for the same price, please retrieve the offer again to get the latest pricing information.
`rate_limit_exceeded`	Too many requests have hit the API too quickly. Please retry your request after the time specified in the `ratelimit-reset` header returned to you
`stale_airline_initiated_change_accept`	The change you tried to accept is not the latest. Please retry the request with the latest one
`stale_airline_initiated_change_update`	The change you tried to update is not the latest. Please retry the request with the latest one
`unavailable_feature`	The feature you requested is not available. Please contact help@duffel.com if you are interested in getting access to it
`unsupported_action`	The resource does not support the following action
`unsupported_format`	The API does not support the format set in the `Accept` header, please use a supported format
`unsupported_version`	The version set to the `Duffel-Version` header is no longer supported by the API, please upgrade
`validation_checksum`	The credit card number provided is not valid
`validation_format`	The field submitted has an invalid format
`validation_inclusion`	The field submitted must be one of a fixed set of values
`validation_length`	The length of the submitted field is out of the boundaries for that field
`validation_required`	The field submitted cannot be blank
`validation_type`	The field submitted has an invalid type
`validation_unique`	The field submitted must be unique

Examples

If you don't provide an authorization header in your request, you'll receive an authentication_error like the following:

JSON
{
  "errors": [
    {
      "code": "missing_authorization_header",
      "documentation_url": "https://duffel.com/docs/api/overview/errors",
      "message": "The 'Authorization' header needs to be set and contain a valid API token.",
      "title": "Missing authorization header",
      "type": "authentication_error"
    }
  ],
  "meta": {
    "request_id": "FZW0H3HdJwKk5HMAAKxB",
    "status": 401
  }
}

If you don't provide a required parameter, or some data you provided is invalid, you'll receive a validation error, with a type of validation_error. Validation errors include an additional source property, pointing to the exact field in your request which was invalid. Here's an example of a validation error returned when a slice in an offer request doesn't have an origin:

JSON
{
  "errors": [
    {
      "code": "validation_required",
      "documentation_url": "https://duffel.com/docs/api/overview/errors",
      "message": "Field 'origin' can't be blank",
      "source": {
        "field": "origin",
        "pointer": "/slices/0/origin"
      },
      "title": "Required field",
      "type": "validation_error"
    }
  ],
  "meta": {
    "request_id": "FZW0cz5rZoJSEekAAK2B",
    "status": 422
  }
}

Error cases guidelines

Some common error cases and possibly misleading scenarios that can happen and how to react to them.

Expired offers

One of the common errors that can be received while creating an order is offer_expired. This error indicates that the selected offer has expired on the Duffel platform and cannot be used to create an order.

If an offer_expired error is received while creating an order, the request should not be retried and a new search should be performed and the resulting offers used instead.

Additionally, the expires_at attribute can be used to ensure that order creation requests are not attempted with expired offers. Every offer contains an expires_at attribute that indicates how long it is valid for (usually 15 - 30 minutes from creation).

JSON
{
  "data": {
    ...
    "expires_at": "2020-01-17T10:42:14.545Z",
    ...
  }
}

Duffel recommends pre-validation of the expires_at attribute of an offer - ensuring it is in the future - before performing an order creation request.

Validation errors

Validation errors refer to invalid inputs or errors in the format expected of a field in the request. They contain a description of the issue in the response field message and require an adjustment to the request for it to succeed. See error types for more information on the different validation errors that can be seen.

Temporary errors

Temporary errors are returned when a transient issue has occurred, either within Duffel or on one of our airlines' platforms. They are safe to retry and should generally work on subsequent attempts.

If these errors are persistent, check Duffel Status or contact support for help.

Passenger age vs. Type mismatches

Some airlines expect an alignment of the passenger types between searching and booking flights. When this misalignment is detected by the airline, a response that indicates a lack of availability is returned and Duffel returns an offer_no_longer_available error.

While it is tricky to determine if this misalignment is the cause of a specific offer_no_longer_available error, the circumstances which generate this misalignment can be easily mitigated by passing in an age instead of type for each passenger when performing searches.

Although Duffel offers the ability to specify passengers in an offer request with a type (e.g. adult, child, infant_without_seat), airlines have varying polices and rules on how to interpret these types. As a result of these variations, there can be occasional mismatches between the passenger types in the search and the eventual order creation.

JSON
{
  "data": {
    "passengers": [
      {
        "type": "child"
      }
    ]
  }
}

To avoid this mismatch between searching and order creation, Duffel recommends to specify the age (e.g. 18) of a passenger when creating offer requests.

JSON
{
  "data": {
    "passengers": [
      {
        "age": 13
      }
    ]
  }
}

Rate Limiting

If you send too many API requests in quick succession, you'll receive a rate_limit_error like the following:

JSON
{
  "errors": [
    {
      "code": "rate_limit_exceeded",
      "documentation_url": "https://duffel.com/docs/api/overview/errors",
      "message": "Too many requests hit the API too quickly. Please retry your request after the time specified in the `ratelimit-reset` header.",
      "title": "Rate limit exceeded",
      "type": "rate_limit_error"
    }
  ],
  "meta": {
    "request_id": "Fkpj57Fn-uB9b0kAANVI",
    "status": 429
  }
}

You'll also receive information about the rate limiting which was applied to your request in the HTTP headers which are returned as part of the response:

ratelimit-limit: 60

This is the limit of requests you can make per interval period. This period is currently set to 60 seconds but is subject to change without notice. If you feel that you may require a larger quota than this, drop us a line.

ratelimit-remaining: 0

This is the amount of requests you can still make during the current period before being rate limited.

ratelimit-reset: Tue, 24 Nov 2020 08:22:00 GMT

This is when your rate limit will be reset, in an RFC 2616 compliant human readable format.