Flights API Error Codes and Troubleshooting

This article covers error responses you may encounter across all Flights API v2 endpoints, along with common issues and how to resolve them.

HTTP Status Codes

Error Response Format

All error responses follow a consistent format:

{
  "status": "error",
  "data": null,
  "message": "A human-readable description of the error."
}

Errors by Endpoint

Autocomplete

Search

Availability

Fare Rules

Create Booking

Confirm / Cancel Booking

Get Booking Details

Common Issues and Troubleshooting

"Missing x-correlation-id" on every request after autocomplete

The x-correlation-id is returned in the response headers (not the response body) of the autocomplete call. Make sure your HTTP client captures response headers and forwards the value to subsequent requests.

Search returns empty results

• Verify the origin and destination airport codes are valid IATA codes.
• Check that the departure date is in the future.
• Try broadening your filters (remove stop or airline restrictions).
• Ensure cabin_type matches available inventory for the route.

"Session not found" on availability check

Search sessions expire after a period of inactivity. If too much time has passed since the search, run a new search to get a fresh cabinsearchsession_id.

"Token expired" when creating a booking

The cabinavailabilitytoken has a limited validity window. Complete the booking promptly after the availability check. If the token expires, run the availability check again.

Booking status remains "TICKETINPROCESS"

Ticketing can take a few moments to complete. Poll the Get Booking Details endpoint at reasonable intervals (e.g., every 10-15 seconds) to check for a final status.

Cancellation penalties applied unexpectedly

Review the fare rules before cancelling. Use the Fare Rules endpoint to check whether the fare is cancellable and what penalties apply per passenger type.

Best Practices

• Always capture the x-correlation-id from autocomplete response headers and pass it through the entire flow.
• Handle token expiration gracefully. Build retry logic that re-runs availability checks when tokens expire.
• Validate inputs before sending requests. Check date formats, required fields, and passenger counts on the client side to reduce 400 errors.
• Implement exponential backoff for 429, 500, 502, and 503 errors.
• Log correlation IDs. Include the x-correlation-id in your logs to help Xeni support trace issues across the flow.

Getting Help

If you encounter persistent errors or unexpected behavior, contact Xeni support at customersupport@xeni.com with:

• The x-correlation-id for the affected request chain
• The full request and response (with sensitive data redacted)
• The endpoint and HTTP method
• Timestamps of when the error occurred

Related Articles

• Getting Started with the Xeni Flights API — Overview of the API and booking flow.
• How to Search for Airports Using Autocomplete — First step in the flow where the correlation ID is obtained.