Errors
One error envelope for every failure, and what each status code means here.
The envelope
Every error is JSON with the same fields, plus anything specific the situation adds.
{
"statusCode": 400,
"error": "BadRequestException",
"message": "TK1 operates 2 legs on 2026-09-12. Pass \"origin\" to choose one.",
"path": "/v1/subscriptions",
"timestamp": "2026-09-12T11:06:12.138Z",
"requestId": "5129839a-26c5-49d2-bf4c-eb4f47d10a03",
"legs": [
{ "origin": "SAW", "destination": "AMS", "carrier": "AJA", "scheduledDepartureLocal": "08:45", "flightId": "1407278900" },
{ "origin": "ISL", "destination": "JFK", "carrier": "TK", "scheduledDepartureLocal": "14:10", "flightId": "1407266450" }
]
}message is a string, or an array of strings when several validation rules failed at once. Quote requestId when you write to us about a request; it is the id in our logs.
Status codes
| Code | When |
|---|---|
400 | The request is malformed, or a value failed validation. For an ambiguous flight number the body carries legs. |
401 | No key, or a key that is invalid, revoked or expired. |
402 | The key's plan caps subscriptions per month and this one would pass the cap (Free: 3). The body carries "code": "watched_flight_limit", limit, used and resetsAt; the subscriptions you have keep running. See quotas. |
404 | No such flight on that date, no leg matching the selector, or no such subscription for this key. |
409 | A subscription for this flight and URL already exists under the same Idempotency-Key. |
429 | A quota window is full. The body names the window and retryAfterSeconds; Retry-After is set. See quotas. |
502 | The upstream data source failed after retries. Safe to retry after a short wait; watched flights are not affected, polling retries by itself. |
503 | Temporarily unavailable, for example during a deploy. Retry with backoff. |
Retrying
429, 502 and 503 are worth retrying; the first with the Retry-After value, the others after a second or two with backoff. 400, 401 and 404 will answer the same way until something in the request changes, and 402 until the month rolls over or the plan does.