API rate limits and fair use

1. Two kinds of limit

Every API key carries two limits, and they fail in different ways:

• Requests per minute. A burst limit that protects capacity over a short window. When you exceed it, the API answers HTTP 429 Too Many Requests with a Retry-After header telling you how many seconds to wait. The same request succeeds once the window has passed.
• Monthly search quota. The number of flight searches your plan includes per calendar month. When it is used up, search requests are refused with HTTP 429 and a body that says the quota is exhausted, until the quota resets on the first day of the next month (UTC) or you move to a larger plan. Retrying does not help; the response says so.

The figures for your key are shown on the API access page of your dashboard and in every response in the headers below. They depend on the plan you chose; a plan's figures are stated when you buy it and can be raised at any time by upgrading.

2. Reading the headers

Every API response includes:

• X-RateLimit-Limit: the number of requests allowed per minute for your key.
• X-RateLimit-Remaining: how many remain in the current minute.
• X-RateLimit-Reset: seconds until the minute window resets.
• X-Quota-Limit and X-Quota-Remaining: your monthly search quota and what is left of it.
• Retry-After on a 429: seconds to wait before retrying.
• X-Cache: HIT when the result was served from our cache (it does not count against your search quota), MISS when suppliers were queried.
• X-Request-Id: quote it when you contact support.

3. What counts as a search

A search is one call to the search endpoint that reaches our suppliers (X-Cache: MISS). Calls answered from our cache, calls that fail validation (HTTP 4xx other than 429) and calls to booking, pricing-confirmation or utility endpoints do not count against the monthly quota, though they do count against the per-minute limit.

4. Caching: ours and yours

• We cache identical searches (same route, dates, passengers and cabin) for a short period and serve repeat requests from the cache. The Cache-Control and Age headers tell you how old a cached result is.
• You may cache a result in your own product for the period the Cache-Control header allows, for the same customer session. Do not serve a cached fare beyond that period and never book from a cached price: call the pricing-confirmation endpoint first, which re-validates the fare with the supplier.
• Do not build fare databases, price alerts or calendars by polling the API. That is not a permitted use; see the API Terms of Use.

5. Fair use and the look-to-book ratio

Suppliers charge us for every search that reaches them whether or not a ticket is sold, and they watch the ratio of searches to bookings on each channel. A key that searches heavily and rarely books looks like a scraper and puts the whole channel at risk. We therefore reserve the right to reduce the limits of, or suspend, a key whose search volume is out of proportion to its bookings, after contacting you first where we can. Genuine traffic from real users, even at high volume, is welcome: talk to us about a plan that fits it.

6. IP whitelisting

Each key must list the public addresses of the servers that call the API. Calls from an unlisted address are refused with HTTP 403 before any limit is consulted. Serverless and cloud platforms often use changing egress addresses; route your API calls through a fixed egress (a NAT gateway or a proxy with a static address) and list that. You can update the list from your dashboard at any time; changes take effect within a minute.

7. Handling a 429 correctly

1. Read Retry-After. Wait that many seconds. Do not retry sooner.
2. If Retry-After is absent, back off exponentially: 1 second, then 2, 4, 8, with a little random jitter, and give up after a handful of attempts.
3. Check the body. If it says the monthly quota is exhausted, stop retrying and raise an alert to a person; only an upgrade or the next month will clear it.
4. Use one shared limiter for all workers that use the same key, so that ten workers do not each assume they have the whole limit.
5. Never retry a booking request blindly. Use the idempotency key so a retry cannot issue a second ticket.

8. Plans and upgrades

Limits are set per plan. Every plan states its requests per minute and its monthly searches; larger plans have higher figures and lower per-search cost. Your current plan and its figures are on the API access page of your dashboard, and you can upgrade there; the new limits apply immediately. Evaluation keys carry the lowest limits and are for building and testing, not for production traffic. If your product needs more than the largest published plan, contact us for a custom limit.

9. Changes to limits

We may change the limits of a plan with at least 30 days' notice by email, except reductions required at once by a supplier or for security, which we explain as soon as we can. We may also raise limits temporarily during an incident recovery or on request for a launch or a campaign.

10. Further reading

Our guide Flight API rate limits, caching and IP whitelisting walks through a client implementation with code, and the API Terms of Use set out what you may do with the data.