API Documentation

Errors

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

CodeReasonDescription
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 on our side. Try again later.

Error responses

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

NameDescription
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:

NameDescription
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:

ValueDescription
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
duplicate_passenger_nameThe order cannot contain more than one passenger with with the same name
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
expired_access_tokenThe provided access token has expired
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_version_headerThe Duffel-Version header must be a known version of our API as inndicated in our Docs
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.
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
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
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

Examples

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": "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:

{
"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
}
}