Found at “Beat the Invisible Man: Unforced errors in API design | Redocly” on 2026-01-30T15:00:41+01:00.

Interesting approach by Adam Altman from Redocly. The concept of “unforced errors” is quite interesting.

In API design and documentation, unforced errors look like this:

• an endpoint that behaves differently than described
• a parameter marked optional that’s actually required
• error responses that aren’t documented or actionable
• examples that don’t compile, don’t run, or don’t match reality
• concepts explained, but not when or why to use them

None of these require a competitor. None require scale. None require bad actors.

Near the end of the article, Adam asks if the API works as expected, without surprises. That immediately made me think of my API Hierarchy of Needs (2013), where its second layer (“Functionality”) asks something similar.