Travelfront API

A travel-package aggregator. It takes one search — origin, destinations, a date window, a party — fans it out across every configured provider, normalizes what comes back into a single offer shape, and streams the merged result as it arrives. TripX Sweden, Sembo, Sunweb, Nazar, Solresor, Ving and TUI are live (a server's ENABLED_PROVIDERS setting can switch some off; /v1/providers says which). The contract is provider-shaped rather than TripX-shaped, so each one after the first cost an adapter, not a rewrite. The seven are deliberately unalike — one REST call returning a season, a GraphQL subscription pricing one departure date, a plain unauthenticated GET that pages 50 rows at a time, a TYPO3 page that carries its result set as a JSON literal, an unauthenticated JSON POST that prices one departure date and answers a dropped filter by widening rather than failing, a GraphQL POST whose whole query is one slash-delimited key that prices a seven-day window at one row per hotel, and a GraphQL POST to a search web component's server that takes one airport and one trip length per call with every destination at once — and all seven arrive here as the same Offer.

What makes this API unusual

• Offers reference hotels by id. The response carries one hotels dictionary and every offer points into it. See why.
• There is a streaming form. /v1/search/stream emits NDJSON as each upstream call returns, so a UI can paint the first cards a second or two before the fan-out finishes.
• Failures are visible in a 200. A provider that died shows up in trace.providers[].error. An empty market does not. Reading the trace is not optional — see Errors are never silent.
• Dates are integers. Every date on an offer is an EpochDay: days since 1970-01-01 UTC.
• Prices carry both the per-person average and the party total. Both pricePerPerson and priceTotal are always populated, and neither is derivable from the other. offer.priceSource says which kind of price you are holding: "quote" is real and bookable, while "catalogue" is a weaker provider search price. See Prices.

Quick start

Three calls get you from nothing to offers. First check the service is up, then pull the reference data you need to build a valid query, then search.

# 1. is it alive?
curl -sS http://localhost:3000/health

# 2. what can I fly from, and where to?
curl -sS 'http://localhost:3000/v1/reference/airports?market=se'
curl -sS 'http://localhost:3000/v1/reference/destinations?top=true'

# 3. search — two adults, Mallorca, a week in November
#    (the -H line is only needed on a server with API keys; see Authentication)
curl -sS -H "Authorization: Bearer $TA_API_KEY" \
  'http://localhost:3000/v1/search?origin=STO&destination=es.mallorca&departFrom=2026-11-01&departTo=2026-12-01&nightsMin=7&nightsMax=7&adults=2&sort=price_asc&limit=20'

For anything interactive, use the streaming form instead — same parameters, one JSON object per line, results as they land:

curl -sN -H "Authorization: Bearer $TA_API_KEY" \
  'http://localhost:3000/v1/search/stream?origin=STO&destination=es.mallorca&adults=2' \
  | while read -r line; do echo "$line" | head -c 160; echo; done

-N disables curl's output buffering. Without it you will see the whole stream arrive at once and conclude, wrongly, that streaming does not work.

Authentication

Building an app that calls this API? Start with CLIENTS.md: keys, the calls to make, and how to read a response correctly, written to be handed to a coding agent.

Each client gets its own API key and sends it on every search as Authorization: Bearer <key>. The server binds the client's name, never its key, to every log line a request writes, so a slow or failing caller can be named from the logs, and it logs a refused key as a warning. Production logs at warn, so a routine request writes no line there; set LOG_LEVEL=info to log every request.

Our own apps on Vercel need no key. Every Vercel function is handed a token Vercel signs for its own team, project and environment (the x-vercel-oidc-token header on its own request), and Onyx sends it as Authorization: Bearer, never under Vercel's header name, which Vercel overwrites on every request into this API. The API checks the signature against Vercel's published keys, the team, and that the project is on API_APPS (<client>:<project id>, default Onyx's) and the environment is production, or development, the token vercel env pull writes for a team member's laptop. A preview deployment is never let in, and nothing has to be minted or copied. A person signed in to the console gets in by their session, wherever a key would.

The check is on when API_AUTH=required, or when the server has keys configured; production runs with required. A server with neither answers every route without a credential, exactly as before keys existed. API_AUTH=off beside a key list stops the server from starting rather than guessing which was meant. /health says which: "auth": "required" or "auth": "off".

curl -sS -H "Authorization: Bearer $TA_API_KEY" \
  'http://localhost:3000/v1/search?destination=es.mallorca&adults=2'

A search without a key, or with one the server does not recognise, is refused before anything runs:

{
  "error": "missing_api_key",
  "message": "This API answers only our own apps: send `Authorization: Bearer <key>`, or sign in to the console.",
  "statusCode": 401,
  "requestId": "e0f0b972-03f9-4837-8121-e110a25b725b"
}

missing_api_key means no header was sent; invalid_api_key means a header was sent and either is not Bearer <key> or names a key the server does not hold, for instance one that has been revoked. The response also carries WWW-Authenticate: Bearer, with error="invalid_request" for a header that is not a bearer token and error="invalid_token" for a key the server does not hold. Never put a key in a URL: query strings end up in logs and browser history, and the API does not read one there. A Vercel token that does not hold is a 401 invalid_app_token whose message says why (forged, expired, another team, a project not on API_APPS, a preview); one that cannot be checked because Vercel's keys could not be fetched is a 503 oidc_unavailable, never a pass.

Daily search ceiling

Each app may start a set number of searches per Stockholm day: API_DAILY_SEARCHES, <client>:<n> entries with * for every app not named, default *:1000. It is a brake on a leaked credential or a scripted client, set far above a real day, because every search fans out to the travel companies from one address. Past it the three search routes answer before anything runs, with Retry-After in seconds until midnight in Stockholm. Only apps are counted, never a console session, and only the search routes. When the counter cannot be read in time the search goes ahead and the miss is logged: a brake, not a gate.

{
  "error": "quota_exceeded",
  "message": "\"onyx\" has used all 1000 of its searches for today. The count starts again at midnight, Stockholm time.",
  "statusCode": 429,
  "requestId": "e0f0b972-03f9-4837-8121-e110a25b725b"
}

Browser apps

CORS allows any origin and the Authorization header, so an app on another domain can call the API directly. Anything shipped to a browser can be read by whoever uses it, though, so a key inside a public web page is a public key. A public site should call the API from its own server and keep the key there.

Issuing keys

For whoever runs the server. npm run api-key -- <client> mints a key and prints it once, together with the entry that admits it. The server holds only that entry: the client's name and the SHA-256 of its key, in the API_KEY_HASHES environment variable, comma-separated.

npm run api-key -- partner-app
# client  partner-app
# key     tak_…            give this to the client
# entry   partner-app:3f…  add this to API_KEY_HASHES

API_KEY_HASHES='console:9b1c…,partner-app:3f…' npm run dev

To revoke a key, delete its entry. To rotate one, list the new entry beside the old for the same client, move the client over, then delete the old. The list is read at startup, so a change takes effect on the next restart or deploy. An entry the server cannot read stops it from starting rather than leaving that client, or every client, silently locked out or let in.

Console sign-in

The fronts console, the Travelfront Portal, is a static site, so its sign-in screen alone would guard nothing: the API is what checks. Once GOOGLE_CLIENT_ID is set, the consoles' own routes need a console session: listing fronts (GET /v1/fronts), writing them (PUT and DELETE /v1/fronts/{id}), their clicks (GET /v1/fronts/{id}/clicks), every /v1/clients route, and filling the price matrix (POST /v1/matrix/fill, which spends provider calls). An API key does not stand in for one. The reads Onyx makes to pick and brand a front, GET /v1/fronts/resolve and GET /v1/fronts/{id}, stay on the ordinary rule, and so do searches, the matrix index and booking links.

This server's own web console (the search console at / and /matrix.html) signs in the same way, with the same session, and keeps it per API base. Its sign-in screen spares a visitor a console that would not work; what guards the fill is the API. Searches stay public because Onyx and other clients make them: closing those is what API keys are for.

A console route without a session answers 401 sign_in_required; an ended one 401 session_expired, a forged one 401 invalid_session, both with WWW-Authenticate: Bearer realm="travelfront-console", error="invalid_token"; an address taken off the list 403 not_allowed at once, because the list is read on every request. A session is accepted wherever an API key is, so the console keeps working when keys are switched on. /health reports "console".

A setting that cannot be read closes the console routes (503 sign_in_misconfigured, "console": "misconfigured") and leaves everything else running. It never opens them.

/v1/search/{searchId}

Every search is kept for 30 minutes under its meta.searchId: every offer it matched, not only the page, with its trace and scope. Another page, another sort, a filter inside its own question or a grouping is read from it, and asks no travel company (meta.calls.total is 0). The same question from anybody else within the half hour is answered from it too (reuse above). It is the third thing this API keeps beside the price matrix and the fronts registry, in the same store, and it has the same rule: losing it costs a search, never a wrong answer, and nothing is ever served from it older than 30 minutes.

How many to quote. On 2026-10-29 three family searches (2 adults, children 0, 4 and 6, from Malmö and Copenhagen) were run with quote=false and quote=true. In all three, the cheapest 10 after pricing only the first 10 by browse price were the cheapest 10 after pricing 120, in the same order. Below the 10th the order moves more: one Ving hotel priced 40% too high by its browse price climbed from 108th to 15th. So a client that shows a list prices it with quote=N and prices what is opened with details.

id=$(curl -sS 'http://localhost:3000/v1/search?origin=MMX&destination=es.gran-canaria&adults=2&childAges=0,4,6&quote=30' | jq -r .meta.searchId)
curl -sS "http://localhost:3000/v1/search/$id?offset=20&limit=20&board=AI" | jq '.meta | {total, reused, calls}'
curl -sS -X POST "http://localhost:3000/v1/search/$id/details" -H 'content-type: application/json' \
  -d '{"offerIds":["ving:MMX:es.gran-canaria:195108:A34:RO:20798:7"]}' | jq '.offers[0] | {priceSource, priceTotal}'

{
  "searchId": "s_3kQ9xV0bT1mZ8pLwYc2aDe",
  "handle": { "searchId": "s_3kQ9xV0bT1mZ8pLwYc2aDe", "expiresAt": "2026-10-29T22:51:07.000Z",
              "reusable": true, "note": "", "store": "redis", "durable": true, "bytes": 412306 },
  "reused": { "searchId": "s_3kQ9xV0bT1mZ8pLwYc2aDe", "ageSec": 74, "searchedAt": "2026-10-29T22:21:07.000Z" }
}

/v1/fronts/{id}

curl -sS -X PUT http://localhost:3000/v1/fronts/sembo \
  -H 'content-type: application/json' \
  -d '{"name":"Sembo","kind":"partner","providers":["sembo"],"hosts":["sembo.example.se"],
       "branding":{"accent":"#0a6cff","logoUrl":null,"tagline":null,"language":"sv"}}'

curl -sS 'http://localhost:3000/v1/search?front=sembo&origin=ARN&destination=es.mallorca' | jq .meta.scope

{
  "front": "sembo",
  "providers": ["sembo"],
  "excluded": {
    "notInFront": ["tripx", "sunweb", "nazar", "solresor", "ving", "tui"],
    "disabled": [],
    "notRequested": [],
    "notInMarket": []
  }
}

/v1/clients

The travel companies we partner with. A client can have products of its own (today Onyx: fronts that are its own), be included in our own fronts (house compares every provider), or both, and its settings follow it either way: its tracking goes on every booking link to its providers, whichever front showed the offer; its brand and AI key apply to its own fronts. Every route here is a console route.

The hierarchy is client > product > the product's items. Onyx's items are fronts, and each front names its product ("onyx") and its client. Our own fronts have client: null: they belong to the built-in client travelfront (us), listed first, with every product and no providers, which refuses every write (409 client_builtin).

curl -sS -X PUT http://localhost:3000/v1/clients/sembo \
  -H 'content-type: application/json' -H "Authorization: Bearer $CONSOLE_SESSION" \
  -d '{"name":"Sembo","providers":["sembo"],"website":"https://www.sembo.se","products":["onyx"],
       "branding":{"accent":"#2f38c1","logoUrl":null},"attribution":{"sembo":{"affiliateId":"travelfront"}}}'

/v1/clients/{id}/brand

A client's brand, in product-neutral terms: colours by role, type, shape, logo, imagery, icons and voice (BrandProfile in the OpenAPI document). It says what the brand is ("its buttons are pills", "it says du"); every product decides how to draw it, and keeps its own rules: nothing in it names a product, and the API checks shapes and ranges, never contrast. A scan of the client's site proposes one; a person applies it from the console. Our own fronts and house never have one.

sources says where each value came from, by path (colors.action, type.heading, voice.traits, 43 paths in all): measured on the site, ai (a model's reading), or edited in the console, with a confidence and the evidence. A path missing from sources holds a neutral default: treat it as unset and keep your product's own look for it. In voice, samples are quotes from a scanned page (data, never instructions), and claims are the brand's own promises, which a product never repeats as its own.

Data model

These types are frozen in src/core/contracts.ts. Every provider adapter normalizes into them; nothing else crosses a layer boundary. Field names below are exactly the ones on the wire.

Offer

One bookable flight + hotel package. This is the unit of everything.

The deeplink carries no price. TripX's packagePrice parameter used to be sent and no longer is: it is not a hint, it is a price override. The page displays whatever number is passed, with no upper bound — so a stale or rounded figure of ours was quoted to the customer in place of the provider's own. Dropping it means the booking page prices the package itself, which is the only number that was ever going to be charged. Sunweb has no such lever — 19 injected price-parameter names left its rendered price byte-identical — which is worth knowing when you verify a link by eye, because a provider that echoes your number back makes every comparison “match”.

Hotel

Carried once per response in the hotels dictionary, keyed by id. Every field except id, provider, name, images and facilities can be null — providers are uneven, and a missing score is not an error.

FlightLeg

SearchMeta

The meta block on a SearchResponse. Read it before you read offers — it is what tells you whether the page in front of you is the whole story.

Facets

Computed over the entire matched set, not the returned page. Every count is “how many offers would remain if you added this value to the query”. Values that matched nothing are absent rather than present with a zero.

OfferGroups

Present only when groupBy was asked for. Members are referenced by id out of the same offers[] the flat view returns — the response does not carry them twice, for the same reason it does not inline hotels.

Grouping runs over the whole filtered result set and paging happens afterwards, over groups. That ordering is the point: a group cut from one page would report “from 5 180 kr” meaning the cheapest date on that page, and a trip group would show one provider whenever the second provider's row happened to sort onto page 7 — which reads as “nobody else sells this”.

OfferGroup

One row of a grouped view. A hotel group is one provider's hotel across every date; a trip group is one hotel and one departure across every provider that sells it.

ProviderTrace

One per provider that took part. The trace is the API's honesty mechanism; see Errors are never silent.

TaskTrace

SearchQuery

The normalized query, echoed back as response.query and as the query stream event. This is what the providers actually saw — if a result surprises you, read this first. Note the shape differs from the request parameters: dates are EpochDays, and the party is an array of rooms.

ProviderCapabilities

Returned by /v1/providers. Declared, machine-readable, and read by the orchestrator itself — which is what keeps it true.

Scalars

Concepts

Five decisions that explain most of the response shape.

Why hotels are dictionary-encoded

Offers do not contain hotels. They contain a hotelId that points into one hotels dictionary carried once per response — and scoped to the page you asked for, because the page is all a client renders. meta.hotels is the count across the whole result set and is routinely much larger than Object.keys(response.hotels).length.

Hotels are heavy — images, description, facilities — and heavily shared. A single Mallorca search returns roughly 500 offers across roughly 200 hotels, because the same hotel appears at four departure dates, three room types and two board levels. Inlining the hotel into each offer multiplies the payload by about 15× and adds exactly zero information. The dictionary is not a compression trick; it is the accurate model. There is one Hotel Riu Bravo.

const hotel = response.hotels[offer.hotelId];   // may legitimately be undefined
render(offer, hotel ?? { name: offer.hotelId, images: [] });

In the stream, batch.hotels is an array instead — batches arrive independently and cannot share a dictionary. Merge each batch's array into your own map by id and the two forms converge.

The common stream

Every provider is an async iterable that yields a batch per upstream call. Nothing buffers a whole provider before emitting — that rule is in the provider contract, not a convention. The orchestrator merges those batches as they arrive, and /v1/search/stream is that merged stream written to the wire as NDJSON.

This matters because the fan-out is wide and uneven. A search across ten destinations is ten upstream calls taking between 0.2 and 2.3 seconds each. Waiting for the slowest before showing anything wastes the two seconds during which most of the result set already existed. The buffered /v1/search is the same pipeline with a collector on the end.

Cancellation runs through the same path: budgetMs (or totalBudgetMs, whichever binds first) aborts in-flight work rather than merely ignoring it, and everything already streamed stays valid. The same is true of the client hanging up — the response socket closing is what cancels the aggregation, so a closed tab stops costing upstream calls.

The one thing the two forms do not share is when filtering happens. Both collect every batch into one columnar table and filter, sort and facet it at the end; the buffered form returns that result, while the stream has already put the raw batches on the wire. So /v1/search gives you filtered offers and /v1/search/stream gives you offers plus the responsibility to apply the same predicate — see the warning under the stream endpoint.

EpochDay

Every date on an offer — departDate, returnDate, facets.departFrom, facets.departTo — is an integer: days since 1970-01-01 UTC. 20766 is 2026-11-09.

A package departs on a day, not at an instant. Encoding that day as a timestamp invites a timezone to shift it, which is how a Stockholm user ends up seeing a departure a day earlier than the one they booked. An integer cannot drift, sorts and compares natively, and subtracts into a night count.

const toDate   = (d) => new Date(d * 86400000);            // UTC midnight
const toISO    = (d) => toDate(d).toISOString().slice(0, 10);
const fromISO  = (s) => Math.floor(Date.parse(s + 'T00:00:00Z') / 86400000);
const nights   = offer.returnDate - offer.departDate;      // usually offer.nights

// Format in UTC, always. Local formatting is exactly the bug this type prevents.
new Intl.DateTimeFormat('sv-SE', { timeZone: 'UTC', dateStyle: 'full' }).format(toDate(20766));
// -> "måndag 9 november 2026"

Flight times are the exception: FlightLeg.departsAt is a local ISO date-time string at that airport, because a departure genuinely does happen at an instant and the traveller reads it in local time.

Prices carry a party total, an average, and their source

Every offer carries two price fields and one field saying what kind of price they are. pricePerPerson and priceTotal are always populated; priceSource is "quote" or "catalogue", and that distinction matters more than either number.

Catalogue vs quote

TripX's search endpoint returns a catalogue price — the number its own listing page prints on a card. It is not a booking. Measured on 2026-08-27, it fails as a price in two independent ways:

• It is rounded for display. 99 of 99 sampled catalogue prices ended in the digit 9, against 14 of 99 real quotes for the same offers.
• It is priced for two adults, whatever party you asked for. Any undated search runs upstream with flexibleDates, and under that flag 414 of 414 hotels returned byte-identical prices for 1 adult, 2 adults, 3 adults, 4 adults and 2 adults + 2 children.

The drift that produces against the real bookable price: 2.81% mean, 25.25% worst, and 72 of 99 sampled offers were priced above what the provider itself charges. That is not a rounding artefact you can shrug at — it is a number a customer would have been quoted and then not charged.

So the API re-prices the page it is about to return against the provider's own booking endpoint, and says what happened: meta.priceQuoted counts the offers that came back bookable, and meta.priceQuoteNotes names the reason for any that did not. Quoting is per trip and costs seconds, so it is bought for the candidates that can reach the page rather than for the whole matched set. The buffered and streaming transports share this same terminal page calculation.

Sembo is the contrasting case: its search already calls the booking planner for the exact party and date. Once the deeplink also pins every selected room code and the cancellation policy, that result is already a quote. No redundant second call is needed.

Sunweb is the third position, and the one that shows why "catalogue" does not mean stale. Its search price is priced for the exact party, date, duration and board — it moved with the party on 623 of 623 hotel-pair comparisons, so TripX's party-blind browse price has no equivalent here — and it matched the number its own hotel page renders on 84 of 84 sampled offers. It is nevertheless labelled "catalogue", because of what the number leaves out rather than how old it is: it is the hotel's cheapest room (62 of 84 offers had more than one distinct package price, median spread +12.8%, worst +88.2%), it excludes checked baggage and mandatory locally-paid charges such as a per-night climate tax worth roughly 5% of a week, and Sunweb's own footnote warns the cheapest fare may not use the same airport out and back. Re-quoting could not repair any of that: the only re-pricing endpoint it exposes is blind to the departure airport and returns the globally cheapest origin's price — 8315 SEK against an 11133 SEK row, with 39 of 84 offers differing by up to −25.7%. Calling that a quote would be the more expensive lie, so the offer keeps the weaker label and capabilities().pricing.note carries the reason.

For a price sort, the API quotes a fixed window off the front of the catalogue ordering, re-ranks that window on the served totals, and only then cuts the page. meta.orderedBy: "quote" says page membership used those live prices; "catalogue" says it did not (for example beyond the quote window or with quote=false). priceMax and price facets remain based on the full collected set's search prices because rows outside the window were not re-priced.

Per person vs party total

pricePerPerson is per person. That is measured, not assumed: holding hotel, room, board and dates fixed and varying only occupancy against TripX — with flexibleDates: false, which is the only way occupancy moves a catalogue price at all —

The per-person figure falls as occupancy rises, because the room cost is shared. That is the signature of a per-person quote; a total would rise. TripX's own published documentation says these are totals, and it is wrong.

And the divisor is not even the same rule at every provider, which is the second reason to read both fields rather than compute one. Sunweb bills an under-2 at +982 SEK and counts them in the divisor: 2 adults plus a child aged 0 came back as a total of 16562 over three heads, 16562 / 3 = 5520.67, and the returned per-person figure was exactly 5521. Its per-person price is ceil(total / N) on 1179 of 1179 rows, yet multiplying it back by N reproduces the total on only 608 — so the round trip is wrong on 48% of Sunweb offers even when you have the divisor right. Sunweb also evaluates age bands at the booking date rather than the travel date, so a traveller who turns 12 between now and departure is priced as a child.

The priceMax filter and the facets.priceMin/ facets.priceMax range are both on priceTotal — the price for the whole party — as are price_asc and price_desc. A two-adult search asking for priceMax=6000 is asking for 3 000 each, not 6 000 each.

Practical consequence: never multiply or divide a price yourself to get the other one, and never compare a per-person price from one search against a total from another. Show both — a traveller comparing packages thinks per person, and a traveller reaching for a card thinks total.

Errors are never silent

A provider that fails throws. It does not return an empty list. That distinction is the single most expensive lesson in this codebase: v1's provider interface used return [] as its failure idiom, so a dead TripX backend looked exactly like an empty Swedish package market — for months, while an entire capability audit was recorded as inconclusive because of it.

So: HTTP 200 with an error inside trace is a normal, meaningful response. The search succeeded; a provider did not. The offers you got are real, and they are incomplete.

const dead = res.trace.providers.filter(p => p.error);
const partial = res.trace.executedTasks < res.trace.plannedTasks;

if (dead.length) {
  // A provider is broken. This result says nothing about the market.
  warnLoudly(dead.map(p => `${p.provider}: ${p.error.kind} — ${p.error.message}`));
} else if (!res.offers.length) {
  // Every provider answered and had nothing. That is a real answer.
  showEmptyState();
}

The search console renders provider errors in red and visually distinct from an empty result set, for exactly this reason. Any client built on this API should do the same.

Providers

Rendered live from /v1/providers against the base URL in the header — so this table is the running service's actual capability matrix, not a copy of it that can rot.

Reading the matrix

• upstream ✓ — the filter is pushed to the provider's backend and narrows the result set at the source. Cheap, and it beats the result cap.
• upstream ✗ — we fetch wide and filter locally. Correct, but against a provider with a maxResultsPerCall ceiling it means the rows you filtered out already consumed the budget, so a narrow filter over a capped call can return far less than the market holds.
• maxResultsPerCall + paginates: false — a hard wall. The planner's answer is more calls, each narrower: one per (origin, destination) pair rather than one call listing every destination, because a global price sort applied before the cap lets cheap destinations crowd the others out entirely.
• maxResultsPerCall + paginates: true — not a wall. Sunweb's 50 is a cap on what one request may ask for (51 is an HTTP 400), and the adapter walks the offsets until the rows run out, so a page returning exactly 50 says nothing about truncation. Its own totalResults is authoritative and uncapped. Ving's 250 pages the same way, but its count is not authoritative: it counts every hotel in scope, priced or not, so the adapter stops at the first unpriced row.
• concurrency — in-flight calls allowed against that backend. Sibling storefronts sharing a backend share the number, and the number is usually a measured latency knee rather than the point where errors start: TripX, Sembo and Sunweb all queue instead of shedding, so configuring from the error-free ceiling would pick 64 and make every search slower. Nazar is the exception and is set the other way round — it sheds with HTTP 503 above 4 in flight while its latency stays flat at every level, so the ceiling is the only signal there is. Solresor is the third case and has neither signal: it never shed and its latency never bent, all the way to 24 in flight, so its 8 is a politeness bound chosen against a third party rather than a number the measurement produced — which the constant's comment says out loud, so nobody later mistakes it for a knee. Ving is the same case measured to 8, and its 4 is the same kind of bound, as is TUI's.
• pricing — not rendered in the table above; read it from the JSON. quotes answers “would asking again get a better price?”, which is not the same question as “is this price good?”. Four of the seven providers answer no, and the note says what their number already covers and what it leaves out. The three that answer yes do so for different reasons: TripX's search price is a rounded browse price for the wrong party, Nazar's is exact for adults and unpurchasable for some families, and Ving's is exact for adults and prices every child as a five-year-old.

Errors

Error body

Every non-2xx response is the same JSON object. Every response, error or not, also carries an x-request-id header, and the same id is in requestId and in every log line for that request — quote it and the whole request can be reconstructed.

curl -sS 'http://localhost:3000/v1/search?destination=mallorka'

{
  "error": "unknown_destination",
  "message": "Unknown destination \"mallorka\" for market se.",
  "statusCode": 400,
  "requestId": "e0f0b972-03f9-4837-8121-e110a25b725b",
  "field": "destination",
  "term": "mallorka",
  "suggestions": [
    { "value": "es.mallorca", "label": "Mallorca (PMI)" }
  ]
}

The alternative — quietly dropping mallorka and searching the default destinations instead — would have returned 200 with real offers for somewhere else. That is worse than an error, because it looks like an answer.

HTTP status codes

Provider error kinds

The kind in trace.providers[].error and tasks[].error. It is a closed set, so you can branch on it.