You’ve been paged for a production incident. The symptom is clear: customer records in system B are wrong. But the records in system A — the canonical source — look fine. Somewhere between A and B, a transformation fired, a mapping silently dropped a field, a retry double-wrote a row, or an orchestration step succeeded while the downstream call it depended on had already failed. You don’t know which, because the thing that sits between system A and system B doesn’t emit traces. It emits success.
That thing in the middle is API integration. And the reason it’s harder to operate than it looks is that most explanations of it stop at “two systems talking to each other” — which is where the real problems begin, not where they end.
API integration is not the moment two systems exchange data. It’s the entire layer of logic, error handling, transformation, and retry that makes that exchange reliable in production — and that layer is where most production incidents actually live.
Why the definition that vendors give you is incomplete
Ask a vendor what API integration is and they’ll tell you about connectors. You point the platform at system A, you point it at system B, you click a few fields together, and the data flows. That’s technically true for the easy cases — a Zap that posts a Slack message when a row is added to a spreadsheet. It stops being true at the moment the workflow matters.
What actually happens in a real integration is a sequence of decisions that need to survive bad inputs, slow downstream services, partial failures, and schema drift. The inbound event arrives, gets authenticated and validated, gets mapped from the source’s data shape to the target’s, gets routed based on something in its contents, waits for a rate limit to clear, gets retried when the first attempt times out, and eventually lands — or doesn’t, in which case the failure needs to be captured with enough context to diagnose and replay.
Each of those steps is integration logic. None of it is a connector. And it’s all the work that decides whether your integration actually runs in production or just passes a demo.
The connector library is what a vendor puts on a slide. The orchestration layer is what you’re actually buying.
The useful definition of API integration includes the orchestration, transformation, and error handling that lives between two systems — not just the moment they exchange a message.
Where the actual failure modes are
The failure modes that send engineering teams to incidents at 2 AM fall into three categories, and none of them show up in a getting-started tutorial.
Silent transformation errors. The transform that runs between system A and system B is correct — in the sense that it runs without throwing an exception. But it drops a field that the target system interprets as a null, which it silently accepts. Two days later someone notices the records are wrong. The integration ran fine. The data is corrupted. This category of failure is impossible to detect without structured output validation on every transform step, and it’s also the one most platforms give you the least help with.
Retry amplification. When a downstream call fails transiently and the integration retries without idempotency controls, you get double-writes. When it retries with exponential backoff but without a dead-letter queue, you lose the event after the last attempt with no record of what happened. Most lightweight automation platforms retry blindly. The integration layer that survives production needs to know the difference between a retryable error and a terminal one, and it needs to capture failures with enough context that a human can replay them with full payload.
Ownership collapse. A workflow ships to production. The engineer who built it moves to another team. Six months later it breaks, and the on-call engineer has to reconstruct what changed and when from a vendor console that stores changes as “last saved by” with no diff, no version history, no branch. The problem is not that the workflow was wrong — it’s that integration logic was never treated as a software artifact with the same review and versioning discipline as application code. The integration layer doesn’t have to be opaque; it’s opaque by default on platforms that store workflow state in their own database rather than your Git repository.
The question nobody asks when evaluating a platform
Most API integration evaluations are driven by connector count and ease of setup. Those are reasonable inputs for a proof of concept. They are the wrong inputs for choosing something that will run your billing events, your onboarding sequences, and your compliance-required data syncs in production.
The questions that matter are about what happens after the demo:
Can you pull a distributed trace for a single workflow run into your existing observability stack — not the vendor’s dashboard, your Datadog or Honeycomb or Grafana instance? When something breaks at 2 AM, your SRE team is already in one console. Making them log into a second one to look at integration traces is a structural blind spot, not a workflow preference. The integration failure rarely exists in isolation; it correlates with an application deployment, a database slowdown, an upstream service degradation. You can only see that correlation if the integration emits telemetry in a format your stack can ingest — which means OpenTelemetry, not a proprietary log stream.
Is the integration logic in your repository? This isn’t an ideological question. It’s an operational one. If your workflow lives in a vendor database rather than your repo, changes to it don’t go through your engineering workflow. They don’t show up in your PR history. Nobody reviewed them. They’re not rollable-back through the same mechanisms as your application code. When that workflow breaks, reconstructing what changed and who changed it is its own investigation, on top of the incident investigation.
Does the bill move with your traffic? Usage-metered pricing models are convenient when integrations run at a steady, low volume. They become expensive at the moment an integration succeeds — when you push it to production, traffic scales, and the meter runs. Retries count. Loops count. Executions on failed runs count, on some platforms. The integration that powers your production stack should cost a predictable amount, because the thing that makes it expensive is the thing that makes it successful.
The evaluation criteria that matter in production are observability format, version control, and pricing model — not the length of the connector catalog.
What “treating integration as software” actually means
The teams that operate API integration stacks without constant surprises are the ones that imported the same engineering discipline they apply to application code: versioning, branching, review, testing, observability.
That means integration workflows checked into a Git repository, not saved to a vendor database. It means changes go through a pull request — with a reviewer, a diff, and a record — before they touch production. It means the same branching model you use for application features applies to integration features: dev branch, staging environment, production deploy, with the ability to roll back to a tagged state when something goes wrong. Not because this is philosophically correct, but because it’s the only way to answer “what changed before this started breaking?” in under five minutes.
It means integration runs emit structured traces that carry a correlation ID from the triggering event through every step of the workflow. Not because observability is fashionable, but because a flat “the sync failed at 02:14” is genuinely useless when the sync failed because a third paginated page returned a 429 after the upstream service degraded, and fixing it requires knowing both facts.
And it means the integration layer has schema contracts, not just data flows. The source’s payload shape drifts. It always does. The question is whether that drift surfaces as a test failure before deployment or as a corrupted record in production three days later.
None of this requires a specific platform. It requires deciding that integration logic is production software and is therefore subject to the same engineering expectations as the rest of the production stack. The tooling follows from that decision; the decision doesn’t follow from the tooling.
The honest tradeoff
Treating integration as software comes with genuine overhead. Git-native workflows require that engineers treat integration changes as code changes — which means reviews, which means coordination, which means the integration that a non-technical teammate wants to update today now has a queue. That friction is real, and it’s worth being honest about it. The answer for most mid-market teams is not to apply the full engineering workflow to every integration — a simple Slack notification probably doesn’t need a PR. The answer is to distinguish between automations and production-critical integrations, and apply engineering discipline to the latter. The integrations that touch financial records, customer data, compliance-required syncs, and AI pipelines are production software. Treat them that way. The lightweight ones can stay lightweight.
Where to go from here
If your team is at the point where integration reliability is a real operational concern — where you’ve had incidents that originated in the integration layer and took longer than they should have to diagnose — the right next move is to audit what your current setup actually gives you: traces in a format your stack can read, workflow versions in a format your team can review, and a pricing model that doesn’t penalize production scale.
Koodisi is built for exactly this stage — OpenTelemetry on every tier from the Community free plan, Git-native workflow versioning, and feature-tiered pricing with no per-execution billing and no overage invoices. If you’re running the standard mid-market mix of automation tools and integration scripts, it’s worth an afternoon on the Community tier to see what your current stack is missing.
For the broader argument on why integration ownership matters — covering cost predictability, observability, and the versioning gap in more depth — see why unobservable integration stacks are the real hidden bill.