Flight API rate limits, caching and IP whitelisting: a guide for developers

Most developers meet flight API rate limits on the day a test script returns 429 Too Many Requests instead of fares. It feels like an obstacle, but the limits, the cache and the IP whitelist all exist for reasons you can design around. This guide explains why flight APIs restrict traffic, how to read the signals the server sends, and how to build a client that stays inside its plan without slowing down your users.

It is written for developers and CTOs who are connecting a flights API to a booking site, an agency back office or an internal tool. If the topic is new to you, start with what a flight API is and come back before you write the search client.

Why flight API rate limits exist

A flight search is not a database lookup. Every search that is not answered from a cache is forwarded to one or more suppliers, and each of them spends computing capacity to price itineraries and check seats in real time. Somebody pays for that capacity whether or not the traveller ever books. The supply chain behind a single search is described in GDS vs NDC vs flight aggregator API.

The industry measures this with the look-to-book ratio: the number of searches sent for every booking made. A client that sends a very large number of searches and rarely books looks like a scraper or a broken loop. Suppliers can answer that pattern with higher costs or restricted access for the whole channel, so every platform between you and the airline has a reason to watch it.

The third reason is fairness. On a shared platform, one customer with a runaway cron job should not make search slower for everyone else. Limits applied per API key keep the damage from one mistake inside the account that made it.

The two kinds of limit: requests per minute and monthly searches

Flight API rate limits usually come in two forms, and they fail in different ways. Treating them as the same thing is a common cause of retry storms.

Requests per minute

This is a burst limit. It protects capacity over a short window and it resets quickly. When you hit it you receive a 429 response, you wait, and the same request succeeds a moment later. The correct reaction is automatic: slow down and retry.

Monthly search quota

This is a volume allowance tied to your plan, and it protects cost rather than capacity. It does not reset for a long time, so retrying does nothing except add noise. The correct reaction is a human one: find the waste, improve the cache, or move to a larger plan.

On IATA.co each plan sets both numbers: the monthly searches and the requests per minute. In code, handle the first as a temporary condition with backoff and the second as a business condition that raises an alert.

Reading rate-limit headers and HTTP 429

The status code for "slow down" is 429 Too Many Requests, defined in RFC 6585. The RFC says the response may include a Retry-After header that tells the client how long to wait, and it deliberately leaves it to the server to decide how clients are identified and how requests are counted. It also states that 429 responses must not be stored by a cache.

The Retry-After header itself is defined in RFC 9110, and the MDN reference for 429 shows a typical response. The value can be a number of seconds or an HTTP date, so a careful client parses both forms.

Good APIs also report your remaining allowance on successful responses, so you can slow down before you are refused. Header names have varied between providers for years, often some spelling of X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The IETF HTTPAPI working group is standardising RateLimit and RateLimit-Policy fields in an Internet-Draft on rate-limit headers. At the time of writing it is still a draft and not an RFC, so always check the exact names in the documentation of the API you use.

Responses from the IATA.co API carry rate-limit headers, and the exact names are listed in the documentation you receive with your API key. Read them on every response, log them, and let your client reduce its pace as the remaining allowance falls.

When a 429 does arrive, handle it in this order:

1. Pause new requests for that API key instead of letting other workers keep sending.
2. Read Retry-After. If it is present, wait at least that long.
3. If it is absent, fall back to exponential backoff with jitter.
4. Retry a small, fixed number of times, then show the user a clear message instead of a spinner.
5. Log the event with the endpoint, the time and the calling feature, so you can find the cause later.

Client-side techniques that keep you under the limit

One queue and a token bucket

Send every outbound API call through one queue instead of letting each web request call the API directly. A token bucket is the usual control: the bucket refills at a steady rate, each request spends one token, and an empty bucket means the request waits. This allows short bursts while holding the average rate.

Set the refill rate a little below the requests per minute in your plan to leave headroom for retries. If you run several application servers, the bucket must be shared between them, for example in Redis, or divided among them. Otherwise every instance believes it owns the full allowance.

Exponential backoff with jitter

Backoff means doubling the wait after each failed attempt, up to a cap. Jitter adds a random amount to each wait. Without it, all the workers that failed at the same moment retry at the same moment and create a new spike, which earns another 429.

Do not search on every keystroke

Most wasted searches come from the user interface, not from the back end. A few rules remove the majority of them:

• Serve airport and airline autocomplete from your own copy of the reference data, never from the flight search endpoint.
• Debounce text inputs so a lookup fires only after the user pauses typing.
• Run a flight search on an explicit submit, not whenever a date or passenger field changes.
• Disable the search button while a request is in flight, and ignore duplicate submits on the server.
• Do not prefetch searches for routes or dates the user has not asked for.

Caching flight search results safely

Caching is the most effective way to reduce your request count. It is also the easiest technique to get wrong, because fares and seats change all day.

What is safe to cache

• Reference data: airports, airlines, aircraft types and cabin names. It changes rarely, so cache it for days and refresh it on a schedule.
• Identical searches for a short time: same origin, destination, dates, cabin and passenger mix. This covers the user who presses back, and two users asking the same question within minutes.
• Your own account data that does not move with each call, such as plan details shown in an admin screen.

What you must never cache

Price confirmation and booking calls must always reach the supplier. These are the two moments when the answer has to be true now, not a few minutes ago. Do not cache error responses either, and remember that RFC 6585 forbids caching a 429.

Choosing a cache key and a TTL

The cache key must include every parameter that changes the result: origin, destination, departure date, return date, trip type, cabin, adults, children, infants and currency. Normalise the values before you hash them, with airport codes in upper case and parameters in a fixed order. If you skip this step, the same search produces different keys and the cache never hits.

The TTL is a trade-off. A longer TTL saves more searches and shows more stale prices. There is no universal number, but think in minutes and not hours for search results, and go shorter for departures close to today, where seats sell faster. Start short, measure how often the confirmed price differs from the cached one, and adjust from your own data.

Why a price re-check exists

Every search result is a snapshot. Between the search and the booking, a fare can sell out or be repriced by the airline. This is why flight APIs separate search from price confirmation, a flow covered step by step in our flight search API integration guide.

On IATA.co, identical searches within a short window are answered from cache, and price and availability are always re-checked with the supplier before a booking is confirmed. Bookings are deducted from your prepaid balance, so the confirmed price is the one that matters. Build your interface to treat "the price changed" as a normal outcome: show the new total and ask the customer to accept it.

IP whitelisting: what it protects and how to set it up

An API key is a bearer secret. Whoever holds it can use it, and keys leak in ordinary ways: a commit, a support ticket, a log line, a mobile app bundle. IP whitelisting adds a second condition, which is that the request must also come from an address you registered. A leaked key is then of no use from the machine of an attacker.

IATA.co API keys only work from whitelisted server IP addresses. One consequence is intended: the API cannot be called from a browser or a mobile app. Those calls belong on your server.

Static egress IPs on serverless and autoscaling hosts

A single virtual server has a fixed address. Serverless functions, container platforms and autoscaling groups usually send outbound traffic from a changing pool of addresses, which cannot be whitelisted. You have three practical options:

• Route outbound traffic through a NAT gateway that has a reserved static IP address.
• Use the static or dedicated egress IP feature of your hosting platform, if it offers one.
• Run a small forward proxy on a server with a fixed IP and send only the flight API calls through it.

Whitelist the production egress address, not the laptop of a developer. For local work, call the API through a staging server or a VPN that exits from a whitelisted address.

IPv4 vs IPv6

Check which protocol your server really uses for outbound connections. A dual-stack host may prefer IPv6, so the API sees an IPv6 address while you registered the IPv4 one, and every call is refused. Confirm the address by calling an IP echo service from the server itself. Then register the form your provider supports, or pin your HTTP client to one protocol.

Keeping keys out of front-end code and repositories

A whitelist is a second lock, not a reason to be careless with the first. The OWASP Secrets Management Cheat Sheet observes that many organisations still keep secrets hardcoded in plaintext in source code and configuration files, and it recommends regular rotation so that a stolen credential only works for a short time.

• Store the key in an environment variable or a secrets manager, never in the repository, and add secret scanning to your CI pipeline.
• Never ship the key in JavaScript, a mobile app or a public config file. The browser talks to your back end, and your back end talks to the API.
• Rotate the key on a schedule, and immediately when someone with access leaves or a leak is suspected.
• Mask the key in logs and error reports.

Monitoring your own flight API usage

Do not wait for the provider to tell you that you have a problem. Record every outbound call with its endpoint, status code, duration, cache hit or miss, and the remaining allowance from the response headers. Then watch a small set of numbers:

• Searches used against the monthly quota, with a projected date on which you would run out.
• The count of 429 responses per hour. In a healthy client it stays close to zero.
• Cache hit ratio for search, which shows whether your keys and TTL are working.
• Your own look-to-book ratio: searches sent for every booking made.
• The features, pages or background jobs that generate the most searches.

Set an alert for when usage runs ahead of the month, and another for a sudden rise in 429s. Both usually point to a bug or a bot, and both are cheaper to find on the first day than on the twentieth.

How IATA.co applies these rules

API access on IATA.co is requested from the dashboard and approved by a person. After approval you receive an API key and the documentation. The key only works from the server IP addresses you have whitelisted.

Each plan sets a number of monthly searches and a number of requests per minute, and responses carry rate-limit headers so your client can pace itself. Identical searches within a short window are answered from cache. Price and availability are always re-checked with the supplier before a booking is confirmed, and every booking is deducted from your prepaid balance and recorded in your statement.

You can read the overview in the flights API section, or create a free account and request access from the dashboard. IATA.co is an independent platform and is not affiliated with the International Air Transport Association (IATA).

A short checklist before you go live

Review this list before you point production traffic at any flights API. It covers flight API rate limits, caching and key security in the order that problems usually appear.

1. All API calls leave from a server with a static, whitelisted egress IP, and you have confirmed whether it connects over IPv4 or IPv6.
2. The API key lives in a secrets manager or environment variable, not in the repository, the front end or the logs.
3. One shared queue or token bucket paces requests slightly below the requests per minute in your plan.
4. The 429 handler honours Retry-After, falls back to exponential backoff with jitter, and stops after a fixed number of retries.
5. Autocomplete runs on local reference data, and flight searches run only on submit.
6. The search cache uses a complete, normalised key and a short TTL. Price confirmation, booking and error responses are never cached.
7. The booking screen handles a price change at confirmation as a normal step.
8. Dashboards and alerts cover quota usage, 429 counts, cache hit ratio and look-to-book.

Test your client against real limits Create a free IATA.co account, verify your email and request API access from the dashboard. Once a person on our team approves the request, you receive your API key and the documentation, and you can test your queue, your cache and your IP whitelist against real responses.