The biggest API mistake isn't bad documentation. It's broken trust

I've been spending a lot of time analyzing APIs and SDKs recently, and one pattern keeps showing up.

Most developers complain about documentation.

I don't think that's the real problem.

The biggest problem is trust.

When developers integrate an API, they need to trust that:

• the documentation matches the actual behavior

• the examples actually work

• the SDK reflects the latest API

• version updates won't silently break production

• error messages help instead of creating more confusion

Once that trust is lost, everything becomes slower.

Developers stop relying on the documentation.
They start reading source code.
They inspect network traffic.
They open Postman.
They ask AI to explain undocumented behavior.

At that point, the API isn't just difficult to use.

It's expensive.

The interesting part is that trust isn't built by having hundreds of pages of documentation.

It's built through dozens of small details:

• Accurate examples

• Predictable error responses

• Consistent naming

• Reliable SDKs

• Clear changelogs

• Stable versioning

• Documentation that stays in sync with the API

I'm curious how other developers see this.

What was the moment an API completely lost your trust?

Was it outdated docs?

A broken SDK?

Unexpected breaking changes?

Or something else?