Rate limits and fair use

FX-Port limits how fast a key can call the API, so that one runaway loop or one abusive client cannot slow everybody else down. The limits are far above what an interactive application needs. This page says what they are, what you get when you reach one, which requests are refused before they cost anything, and how to stay comfortably below them.

Limits per key

Every API key has a counter per minute (the minute of the clock, not a sliding window) for each of three groups of endpoints. Sandbox keys have the same counters as live keys.

The counter belongs to the key, not to the agency or the IP address: two keys of one agency count separately. A request that is refused for another reason (a malformed body, for example) still counts, so a client that loops on a bad request burns its own budget.

Heavy endpoints have a second, tighter protection

A search costs a supplier real work, so searches and hotel name searches are also limited by how many run at the same time and by short bursts. These ceilings sit well above what a user-driven application produces, and they protect the suppliers (and your other calls) from a loop that fires thousands of searches at once.

• Sandbox keys get a quarter of every number in this table.
• All the keys of an agency together get three times the numbers of one key.
• A key can keep 4 streams (stream=true) open at the same time.
• A call that has to wait for a free slot waits up to two seconds inside the API before it is refused with concurrency_limit_exceeded.

When you reach a limit

The API answers 429 with an error code that says which limit, and tells you when to come back:

A 503 with service_overloaded or supplier_busy means the service or a supplier is shedding load for a moment: the answer is the same, wait and retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 17
ratelimit-limit: 6000
ratelimit-remaining: 0
ratelimit-reset: Sun, 01 Nov 2026 15:20:00 GMT
ratelimit-policy: 6000;w=60
x-fx-limit-class: flight_search

{
  "environment": "live",
  "success": false,
  "errors": [
    {
      "code": "rate_limit_exceeded",
      "type": "rate_limit_error",
      "title": "Rate limit exceeded",
      "message": "Too many requests hit the API too quickly. Retry after the number of seconds in the Retry-After header.",
      "field": null,
      "details": { "retry_after": 17 },
      "documentation_url": "https://fx-port.com/docs/errors#rate_limit_exceeded"
    }
  ],
  "meta": { "request_id": "req_8f3a9c1d2e4b", "status": 429 },
  "request_id": "req_8f3a9c1d2e4b"
}

The ratelimit-* headers are on every response of a key, not only on a 429, so you can slow down before you are refused. Wait for Retry-After, then retry with exponential backoff and jitter (see Errors).

Refused before they cost anything

Some requests never reach a supplier, so they cost neither you nor us anything:

• Malformed input. A wrong airport code, an impossible or out-of-range date, an absurd passenger count, an unknown enum value or a body that is not a JSON object is answered with 400 and a stable code (see Errors) before any supplier is called, and it does not count as a supplier failure.
• Oversized bodies. A search or price request may be up to 64 KB, any other JSON request up to 256 KB, an ACD upload up to 26 MB (10 MiB per file). Larger bodies get 413 request_too_large before they are read.
• A key that is not a key. A key that does not have the shape of an FX-Port key (fxp_live_ or fxp_test_ followed by 16 to 64 letters and digits, 80 characters at most) is refused at once with 401 invalid_api_key_format, without a lookup.
• Repeated bad authentication. Requests with an unknown or malformed key are limited per IP address (30 a minute, a burst of 20). After repeated failures that address is blocked for a minute, then for longer if it continues, up to an hour. Requests with a valid key are never affected, even from the same address: an office behind one address is safe.

The typeaheads

The airport and destination lookups need no key, so they are limited per IP address instead (1,200 a minute, a burst of 300). They answer Cache-Control: public, max-age=60: let your browser or your CDN cache them, and debounce your input.

Stay comfortably below the limits

If you plan a load test or a bulk job, tell us at [email protected] first. Sandbox keys have a quarter of the heavy-endpoint ceilings, and the suppliers' test systems are small.

Related limits

The limits of each endpoint are in its page and in the API reference.