An API can return a number without telling you what it means

An external data provider returns a number. It's clean, it's typed, it even arrives with a label — a currency code, a timestamp, a field name. You store it, show it, compute on it, and file the integration under done. The fetch really is done; that part you should rent and stop thinking about. But "we can pull the number" and "we know what the number means" are two different claims, and the line between them is where a data integration is won or lost — usually months after the demo, when the number that always looked right turns out to mean something other than what the system assumed.

What the capability gives you

A data provider — a market-data feed, a CRM, a payments processor, an accounting system — does a genuinely hard job so you don't have to. It gathers, normalizes, and serves data you would otherwise collect, clean, and host yourself: prices across thousands of instruments, a company's filed statements, a customer's record in a system you don't run. That's the clearest kind of capability to rent — high effort, well-solved, not your product. Rebuilding it would be a mistake. So the model is right. The question is what you keep on your side of it.

What stays yours: the meaning

The provider owns the value — the number, the record, the field, and the work of producing it. You own the meaning — what that value is denominated in, as of when, what a blank in it stands for, and whether two values the provider handed you are even comparable. This is the part that feels handled and isn't. A market capitalization and a balance sheet can both be perfectly correct and still not belong in the same calculation, because one is quoted in the trading unit and the other in the company's reporting currency. "This figure is in pence, as of last night's close" is a sentence about your system's understanding of the number. "The API returned 143,699,911,468" is a sentence about the provider. They belong in different places, owned by the side that actually knows them — and the side that knows what a number means is always you, because meaning is a fact about your product, not about their endpoint.

In plain terms: a number needs a unit and a date before it means anything, and the provider doesn't always carry both inside the value. In technical terms: apply one exchange rate across fields quoted in different units — a market value in a trading sub-unit, a statement in the reporting currency — and every metric derived from them is silently wrong, while each individual figure still looks reasonable on its own.

What breaks when it's hacked in

The failure has one shape: the provider's value is treated as truth instead of as raw input. Everything else is a consequence.

A feed returns a market capitalization with a currency code attached. The code is honest — the parent currency. But the value is in a sub-unit, a hundredth of that currency (pence under the pound, agorot under the shekel). Convert it with the parent-currency rate and an eleven-billion company is published as an eleven-hundred-billion one. Nothing threw an error; the number was real; it simply meant one-hundredth of what the system assumed.

Or two values that are each correct combine into a third that is nonsense: a market value quoted in one currency divided by a balance-sheet figure filed in another, with no conversion between them. The ratio explodes, though both inputs are exactly what the provider intended. This is the quiet one — it hides until a metric joins two valid numbers, then surfaces as a company that looks a thousand times larger or smaller than it is.

None of this is special to market data. A CRM hands back a "customer" and the product treats it as the source of truth until the local copy and theirs quietly stop agreeing about who owns what. A payments webhook gets read as the live answer to "what is this person allowed to do," until it's slow at the worst possible moment. An accounting figure arrives in minor units and a report is suddenly out by a factor of a hundred. The capability changes; the shape of the failure doesn't — a value the product never learned to interpret, trusted as if it had.

It almost never shows up in the demo, because the demo uses one familiar, well-behaved record — a US-listed stock priced in dollars, one customer, one paid invoice — where the value and its meaning happen to coincide. It shows up the first time a foreign name, an edge-case record, or a second currency enters the set.

Worth being precise about whose problem this is: in the cases above, the provider mostly did its job. It sent a currency code on every record, returned internally consistent values, documented its endpoints. The gap is that the meaning of a value lives in conventions — units, currency, as-of date, what null stands for — that the value doesn't carry and the docs don't always spell out, and reconstructing that meaning at the boundary is the integrator's responsibility, not the provider's failing. When something genuinely is ambiguous — a value whose label and magnitude disagree — the honest move is a precise, evidence-backed question to the provider, not a complaint and not a guess.

Sometimes it's the envelope, not the value

The currency case is the gentle version — the provider was honest, and the meaning was simply yours to add. There is a second version worth planning for, where the response itself is what needs checking, independently of whether the number inside it is right.

A malformed request can be answered confidently rather than refused. A rate limit can arrive shaped like a success, so a system that reads only the status code writes nothing over good data and never learns why. Reference examples drift out of step with live data as an API grows. None of this is peculiar to one provider or one kind of feed, and none of it is a mark against anyone — it is what happens to any long-lived API surface carrying more than one generation of decisions, and the same shapes recur across feeds of every kind.

In plain terms: the response can't always be trusted to tell you the truth about itself. In technical terms: the envelope is unreliable independently of the value, so the boundary has to confirm the response is the one it asked for — the echoed identifier matches the request, the status is genuinely a success, the shape is what this endpoint returns on this plan — before it ever reaches the question of what the number means.

This doesn't move the conclusion; it sharpens it. Whether the gap is a meaning the provider never carried or a contract the provider didn't keep, the cost lands in your product, and the defense lives in the same one place.

The fix is a boundary, not a patch

The fix isn't a sharper parse bolted on wherever a number looked wrong. It's a seam. At the point where external data enters, every value is checked against what it's supposed to mean, and the system returns one of two things: a value it can stand behind, or nothing, plus the reason it couldn't. A balance sheet that doesn't balance is flagged, not shown. A market value whose units can't be resolved is held back, not published. The product downstream reads from a layer that has already decided what it can and can't vouch for — so it never has to show a confident wrong number, because the boundary refused to manufacture one.

This isn't theoretical. It runs in production under CompanyGraph, on a live financial-data pipeline built around a market-data provider. The boundary isn't a diagram in a design document — it's a screen an operator can open, showing every station between the provider's response and a reader's page, and beside each one the thing it deliberately doesn't do:

Two things on that screen matter more than the architecture. The first is that the boundary counts its own coverage: 40 of 151 imported columns carry a check, and the 111 that don't are listed by name instead of left to be assumed. The second is that it keeps what it removed apart from what it merely flagged — 208 values withheld as implausible, against 8,714 companies carrying a flag that annotates a figure without deleting it. Neither number is typed into the page; both are measured each time it loads, so it can't drift into claiming a thoroughness the code no longer has.

That last part is the one worth copying. The usual alternative isn't a lower number — it's no number, because nothing was counted and every column was published as though it had been checked.

Underneath the map, the individual decisions are inspectable too. The conversion from a company's reporting currency into a comparable base is made explicit and visible, not assumed in passing:

And the pipeline's state is a screen, not a guess. Every data type carries its own freshness window, and the admin shows, per service, exactly what's current, what's gone stale past that window, and what was never fetched — so an operator can answer "is this right?" without reading the logs or the database:

The honesty extends down to the per-statement detail. Dividends sit at 44% coverage with the 2,071 missing records counted, not hidden — so "we don't have this yet" is a visible state, not a silent gap:

In plain terms: when the system can't be sure what a number means, it says so instead of showing something wrong. In technical terms: a single boundary owns every provider call and every interpretation — one place that records what was fetched, converts it deliberately, and attaches a reason whenever it returns nothing — so the trust decision lives in exactly one place and can't be bypassed by the next feature in a hurry.

What it actually takes

A data feed you can trust isn't really the feed. It's the boundary around it — the layer that owns what the numbers mean, marks the uncertain ones uncertain, and stays legible to an operator as the edge cases accumulate. That boundary is a thing with an owner, an admin, and a written policy for what happens when data is stale, missing, or impossible to interpret. It's also the part that doesn't show up in a demo and doesn't get built by a single GetAsync call — which is why it's worth building deliberately, once, rather than discovering it one production surprise at a time.

If that's where your product is — leaning on a market-data feed and needing the boundary built properly — the TwelveData pipeline package scopes exactly this work: the import universe, the update lifecycle, the meaning layer, and the operator admin to see all of it. It's the same architecture running inside CompanyGraph today, offered as a bounded build.

---

The same argument runs through every rented capability, not just data feeds: a payments provider owns the charge, but you own what a paid plan entitles; a language model owns the text, but you own what you'll stand behind. Rent the hard external job; own the record that says what it means.