Authentication and quotas

The key

Every request carries your key in the x-api-key header. Authorization: Bearer <key> is accepted too.

curl "https://api.flightbyte.dev/v1/flights/TK/1848/2026-09-12" \
  -H "x-api-key: $FLIGHTBYTE_KEY"

A free key comes from signing up; paid plans are issued from the request form. Treat keys as secrets: keep them server-side, never in a browser or a mobile app. If a key leaks, rotate it in the dashboard; the old one stops working the moment the new one is issued.

The only endpoints that work without a key are the flag images under /v1/flags, which are meant to be referenced straight from HTML.

Quotas

Your keys share three independent windows: requests per minute, per day and per month, sized by your plan. They are aligned to UTC: the minute window resets on the minute, the day at 00:00 UTC, the month on the first.

Every response tells you where you stand:

X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 117
X-RateLimit-Reset-Minute: 1789306080
X-RateLimit-Limit-Day: 10000
X-RateLimit-Remaining-Day: 9814
X-RateLimit-Reset-Day: 1789344000

Reset values are Unix seconds. A window with no limit sends no headers.

Subscriptions are counted separately: each one a key creates in a UTC month is a watched flight. Paid plans have no cap and bill flights past the plan's allowance. Free has a cap of 3, and the fourth subscription in a month is refused with 402 and "code": "watched_flight_limit", while the three you have keep running.

When a window is full

The request is refused with 429, a Retry-After header, and a body that names the window:

{
  "statusCode": 429,
  "error": "TooManyRequests",
  "message": "Quota exceeded for the current minute window (120/120).",
  "window": "minute",
  "retryAfterSeconds": 23,
  "path": "/v1/flights/TK/1848/2026-09-12",
  "timestamp": "2026-09-12T10:41:37.000Z",
  "requestId": "5129839a-26c5-49d2-bf4c-eb4f47d10a03"
}

A refused request does not consume any window. The three checks happen atomically, so a request that fails the daily limit does not eat a minute or a month.