Errors
All errors return a consistent JSON structure with an error object. The HTTP status code indicates the category of error.
Error response format
Error response
{
"error": {
"type": "invalid_request",
"code": "invalid_airport_code",
"message": "origin must be a supported 3-letter IATA code.",
"field": "origin"
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Error category: "invalid_request", "auth_error", "billing_error", "not_found", or "upstream_error". |
| code | string | Yes | Machine-readable error code (see table below). |
| message | string | Yes | Human-readable error message. |
| field | string | No | The request field that caused the error, when applicable. |
Error codes
| Code | Status | Description |
|---|---|---|
| invalid_airport_query | 400 | Airport search query is shorter than 2 characters. |
| invalid_airport_code | 400 | Origin or destination is not a supported 3-letter IATA code. |
| duplicate_route_airports | 400 | Origin and destination are the same airport. |
| invalid_date_range | 400 | Return date is earlier than departure date. |
| missing_return_date | 400 | Round-trip request is missing the return_date field. |
| too_many_passengers | 400 | Total passenger count exceeds 9. |
| invalid_infants_on_lap | 400 | Lap infants exceed number of adults. |
| invalid_market | 400 | Market is not a valid 2-letter country code. |
| unsupported_market | 400 | Market is valid but not currently supported. |
| invalid_airline_code | 400 | An airline code is not a valid 2-character code. |
| conflicting_airline_filters | 400 | airlines_include and airlines_exclude share codes. |
| empty_airline_filter | 400 | airlines_include or airlines_exclude was provided but empty. |
| invalid_time_range | 400 | departure or arrival earliest_hour is greater than latest_hour. |
| invalid_fare_request | 400 | Fare request could not be translated into a valid upstream request. |
| invalid_booking_request | 400 | Booking request could not be translated into a valid upstream request. |
| missing_booking_fields | 400 | Manual booking request is missing required fields. |
| conflicting_booking_lookup_mode | 400 | Request mixes ignav_id with manual, passenger, or market fields. |
| missing_inbound_carrier_code | 400 | inbound_carrier_code is required when return_date is set. |
| missing_inbound_flight_number | 400 | inbound_flight_number is required when return_date is set. |
| unexpected_inbound_flight_number | 400 | return_date is required when inbound_flight_number is provided. |
| unexpected_inbound_carrier_code | 400 | return_date is required when inbound_carrier_code is provided. |
| ignav_id_not_found | 404 | The ignav_id was not found. |
| itinerary_not_found | 404 | Could not find the specified itinerary. |
| api_key_required | 401 | The X-Api-Key header is missing. |
| invalid_api_key | 401 | The X-Api-Key header is invalid. |
| email_not_verified | 403 | Email must be verified before calling API endpoints. |
| billing_required | 402 | Billing setup is required after free requests are exhausted. |
| billing_blocked | 402 | Billing is blocked for this account. |
| invalid_request_body | 400 | Request body is invalid (missing fields, wrong types, malformed JSON, or extra fields). |
| unable_to_complete_request | 424 | An upstream error occurred. Retry the request or try different parameters. |
Ready to get started?
Create a free account to get your API key, or try the playground — no signup required.