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

Status codes

200OKThe request was successful
201CreatedThe request was successful, and a new resource was created
204No ContentThe request was successful, but there is no response to send back
400Bad RequestThe request was invalid, for example due to missing headers
401UnauthorizedAn access token wasn't provided, or the provided token was invalid
403ForbiddenA valid access token was provided, but it didn't have sufficient permissions
404Not FoundThe requested resource doesn't exist
406Not AcceptableThe response type you requested with your Accept header isn't supported
422Unprocessable EntityA validation error occurred
429Too Many RequestsYou made too many requests to the API in a short period of time
500Internal Server ErrorSomething went wrong. Please contact our support team and attach the request_id to your message. You should not retry this request.
502Bad GatewayBad gateway error. Please contact our support team and attach the request_id to your message. You should not retry this request.
503Service UnavailableThere 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.
504Gateway TimeoutGateway timeout error. If the error persists please contact our support team and attach the request_id to your message. Please retry later.


Error responses

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

titleA quick and simple description of what went wrong
messageA more detailed human-readable description of what went wrong
documentation_urlA URL pointing to a place in our documentation where you can read about the error
typeA machine-readable identifier for the general category of error
codeA machine-readable identifier for this specific error

Error types

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

authentication_errorThere was a problem with authenticating you - for example, you didn't provide an access token or it was invalid
airline_errorWe've received an error back from the airline - for example, your booking has already been cancelled
invalid_state_errorYou 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_errorYou made too many requests to the API in a short period of time
validation_errorYou 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_errorThere 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_errorSomething 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_foundThe access token used is not recognized by our system
airline_internalThe airline has responded with an internal error, please contact support
airline_unknownThe airline responded with an unexpected error, please contact support
ancillary_service_not_availableRequested ancillary service item(s) (e.g. seats) are no longer available, please update your requested services or create a new offer request
already_acceptedThe airline has already accepted the order change
already_cancelledThe provided order has already been cancelled
bad_requestThe request was unacceptable
duplicate_bookingA booking with the same details was already found for the selected itinerary, please select another offer
duplicate_passenger_nameThe order cannot contain more than one passenger with with the same name
expired_access_tokenThe provided access token has expired
insufficient_balanceThere 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_permissionsThe provided token doesn't have sufficient permissions to perform the requested action
internal_server_errorThere was something wrong on our end, please contact support
invalid_authorization_headerThe Authorization header must conform to the following format: Bearer API_TOKEN
invalid_content_type_headerThe Content-Type should be set to application/json
invalid_data_paramThe data in the request body should be a JSON object
invalid_loyalty_cardThe airline did not recognise the loyalty programme account details for one or more of the passengers
invalid_version_headerThe Duffel-Version header must be a known version of our API as indicated in our Docs
malformed_data_paramThe data in the request body is not valid
missing_authorization_headerThe Authorization header must be set and contain a valid API token
missing_content_type_headerThe Content-Type header needs to be set to application/json
missing_data_paramThe data in the request body should be nested under the data key
missing_version_headerThe Duffel-Version header is required and must be a valid API version
new_airline_initiated_changeThere is a new change to your order. Please try again later
not_foundThe resource you are trying to access does not exist
offer_no_longer_availableThe provided offer is no longer available, please select another offer or create a new offer request to get the latest availability
order_change_already_actionedThe order change has already been actioned and cannot be actioned again
order_not_createdThe request to create an order was not successful. You should not retry this request.
rate_limit_exceededToo 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_acceptThe change you tried to accept is not the latest. Please retry the request with the latest one
unavailable_featureThe feature you requested is not available. Please contact if you are interested in getting access to it
unsupported_actionThe resource does not support the following action
unsupported_formatThe API does not support the format set in the Accept header, please use a supported format
unsupported_versionThe version set to the Duffel-Version header is no longer supported by the API, please upgrade


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

"errors": [
"code": "missing_authorization_header",
"documentation_url": "",
"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:

"errors": [
"code": "validation_required",
"documentation_url": "",
"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

Rate Limiting

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

"errors": [
"code": "rate_limit_exceeded",
"documentation_url": "",
"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.