The integration nobody scoped is the one that moves the launch date

Ask why a build slipped and the answer is rarely the hard part. It is almost always an integration that appeared in the plan as one line, because there was documentation and the documentation looked complete.

The documentation is complete. It describes the happy path, and the happy path is not where the time goes.

What the docs cover and what the estimate needs

A vendor’s reference tells you the endpoints, the authentication and the response shapes. From that you can estimate the code that calls it, which is genuinely small — often a day.

What it does not tell you is what the system does when the call does not behave. That is the rest of the work, and it is most of it.

Partial failure. A request that creates something remotely and then fails locally leaves two systems disagreeing. Deciding what happens next — retry, reconcile, alert, roll back — is design work, and it has to happen per operation rather than once.

Idempotency. If you retry, does the vendor create a second record? Some support an idempotency key, some support it on certain endpoints, and some document it without implementing it consistently. Finding out is empirical.

Rate limits under real load. Published limits describe steady state. What matters is behaviour during your import, your month-end job, your launch. The failure mode differs too: some return a clear status with a retry-after, others degrade, others silently drop.

Their outages. They will have some. What your product does during one is a product decision — queue and continue, degrade visibly, or stop — and it needs deciding before it happens rather than during.

The mapping problem underneath

The deeper cost is that two systems rarely agree on what things are.

Both have a customer. One allows several contacts per customer, the other assumes one. Both have an order. One treats a cancelled order as deleted, the other keeps it with a status. One has a field you need and makes it optional, so it is empty in a third of records.

Resolving those means deciding which system owns which fact and what happens when they disagree. That is not coding, it is a series of small policy decisions that need someone who understands the business — and it is the part that gets discovered mid-build, because nobody looks at real data until they are connecting to it.

Two hours that change the estimate

Before committing to a date, do this against the real API with real credentials.

Pull a hundred real records and look at what is actually populated. Not the schema — the data. Optional fields that are always empty, enums with values not in the docs, dates in a format the reference does not mention. This alone changes most estimates.

Then force three failures on purpose. Send a duplicate and see whether you get one record or two. Exceed the rate limit and read exactly what comes back. Kill the connection mid-write and see what remains on their side.

Those two hours convert an integration from a line item into a scoped piece of work. They also occasionally reveal that the thing you planned to build is not possible, which is much cheaper to learn now.

The estimating heuristic

The call is a day. The error handling, the mapping, the reconciliation and the operational behaviour are the project. If an estimate does not name them separately, it is an estimate of the happy path, and the happy path always came in on time.

This is most of what we do in integrations and APIs, and the discovery above is where we start rather than where we end up. If you are weighing whether to run it in-house, we set out the tradeoffs in in-house team vs development agency.