Picture this: you’re a developer, three cups of coffee deep, staring at a 400 error that the documentation describes as ‘invalid request format.’ The example code in the docs is two versions out of date. The forum thread with the answer is locked. The only working solution is buried in a GitHub comment from 2019, written by someone who has since left the company. You’ve burned six hours. Your sprint deadline is tomorrow. And somewhere in a product meeting across town, someone just greenlit the enterprise support tier.

This is not an accident. The economics of deliberately confusing API design are hiding in plain sight, and once you see them, you cannot unsee them.

The Confusion Is the Product

Here is the uncomfortable truth about API complexity: the companies that make billions from developer tools are rarely the ones with the best APIs. They are the ones who found the right friction to monetize.

Salesforce is the canonical example. Their API is notoriously labyrinthine, with multiple API types (REST, SOAP, Bulk, Streaming) that serve overlapping purposes, rate limits that vary by edition, and authentication flows that have changed so many times that even experienced developers Google them every time. Is this because Salesforce can’t hire good engineers? Of course not. It’s because that complexity created an entire ecosystem of certified consultants, implementation partners, and premium support contracts that generate as much revenue as the core product itself.

Twilio did something similar but more subtle. Their core SMS API is actually quite clean. But the moment you need anything beyond basic messaging, you fall into a nested hell of sub-accounts, regulatory compliance flows, and webhook debugging that almost always ends with a support ticket or a professional services engagement. The simplicity at the top is a funnel. The complexity underneath is the business.

Why Documentation Is Always Broken

One reason API confusion persists is that tech documentation is always out of date because keeping it current is nobody’s job. Engineers write docs when they ship features. Nobody writes docs when features change. Nobody owns the process of reconciling what the API actually does with what the docs say it does.

But here is where the cynicism earns its place: companies that want clear documentation figure it out. Stripe, for years the gold standard of developer experience, proved that great API docs are possible. They hired technical writers. They tested documentation with real developers. They treated the docs as a product.

They did this because their business model required it. Stripe’s growth came from self-serve developers who could integrate payments without talking to a sales rep. Every hour a developer spent confused was a lost conversion. So Stripe optimized against confusion, because confusion cost them money.

For Salesforce, Oracle, or SAP, confusion generates money. The incentive runs the opposite direction. The documentation is bad because bad documentation sells consulting hours.

The Three Flavors of Deliberate Friction

Not all API friction is created equal. After watching this play out across enough companies, the patterns fall into roughly three categories.

The first is authentication complexity. OAuth flows with multiple redirect steps, rotating secrets, and scope systems that require reading a whitepaper to understand are almost never necessary at the scale where developers first encounter them. But complex auth flows create dependency. Once your team has spent two weeks getting auth working, you are not switching providers.

The second is rate limiting opacity. Companies rarely publish their rate limits clearly. They give you a limit, but not what counts against it, when the counter resets, or how different API endpoints interact with the same quota. This forces developers to build in retry logic and error handling that embeds the API deeper into their codebase, which is exactly the kind of lock-in that makes switching costs real. This connects directly to how tech companies deliberately cripple their best features as a business strategy, keeping the good stuff just out of reach until you upgrade.

The third is versioning chaos. APIs that deprecate old versions without adequate migration paths, or maintain so many simultaneous versions that the right one is genuinely unclear, keep developers in a permanent state of mild anxiety. That anxiety translates into enterprise support contracts and account managers who can answer questions that the documentation refuses to.

The Hidden Cost Being Externalized

What makes this strategy particularly effective is that the cost is externalized onto developers and their employers, not the API provider.

When a developer burns six hours debugging a broken integration, the API company’s quarterly numbers do not reflect that. The developer’s company absorbs the cost. The developer absorbs the stress. The API company collects the subscription fee and, if things go sideways enough, the support tier upgrade.

This is the same logic that governs cloud storage pricing, where the product being sold is never quite what it appears to be. The API is not really the product. The dependency is the product. The confusion is the delivery mechanism for creating that dependency.

Small startups sometimes break this pattern, and it is usually because they have to. Early-stage startups win by strategically knowing less than incumbents, which often means they build simpler, cleaner integrations because they cannot afford the overhead of complexity. That simplicity can become a genuine competitive advantage before growth and enterprise sales pressure push them toward the same friction-as-revenue playbook.

What Developers Can Actually Do

The honest answer is not much, individually. But there are a few things worth keeping in mind.

First, treat API simplicity as a genuine evaluation criterion when choosing tools. Stripe’s developer experience was not charity. It was a product decision. Companies that build clean APIs are signaling something about how they think about their customers.

Second, budget for integration complexity as a real cost. If a vendor’s API has a reputation for being painful, price that into your estimate. The hours you spend fighting authentication flows and chasing down deprecated endpoints are not free.

Third, watch how a company responds to developer complaints. Companies that treat confused developers as a support problem to be solved are different from companies that treat confused developers as a revenue opportunity to be managed. You can tell which kind you are dealing with within about two forum posts.

The companies that profit from API confusion have run the numbers. They know exactly how much friction the market will tolerate before developers walk. They are parked just inside that line, collecting the toll. The least you can do is know you are paying it.