Not handling error semantics well: sometimes things fail, and thinking through what happens when they do fail is one of the more complex problems in programming. I can easily just write more code to handle authentication or interoperability (I'm a programmer: I write code; I have no fear of writing a lot of code), I have never found APIs with "poor documentation" to be a serious issue, and the terms of service on APIs are usually fine.<p>The real problem is that when the API fails I get back what... one of a massive set of possible error conditions with opaque code numbers and some random english string that I guess I have to render all the way out to the user in the hope that they understand it or that it is even relevant to them? Are new error states going to be added in the future? Who even caused the error, so I know who to give it to: was it me, was it the user, or was it a natural disaster?<p>What happens if the response from your server to mine is lost after you've already committed the change; is there an idempotent way I can verify what happened? Is it ever the case that I can get back a success and the request didn't actually work after the fact? If so, how do I figure out what requests failed, and am I stuck occasionally making, quite literally, a few million requests to check the status of every transaction I've ever previously executed?<p>If you are making callbacks to my server (ugh, this always sucks, and should be avoided except as a notification to cause an early poll: you can design systems that are both efficient in requests and don't require push) are you retrying failures? What do you even consider to be a failure? Again, is there an idempotent way that I can determine whether I've already seen the callback when retried? When retries happen, what happens to the ordering between messages?<p>Most web APIs these days seem to believe "oh, I'll make some really pretty documentation for a single call that shouldn't be able to fail anyway, and yeah... webhooks!", and the result is a horrible mishmash of garbage that, when it fails, simply "fails" in a way that pretty much requires a human to go interact with the state of the entire system and figure out what may have been forgotten or lost, or worse: how to fix the result.
Not giving practical How-To instructions. Reference material in itself is very slow to work with, especially with new development. Documentation needs to include real examples of different calls, and the use of multiple calls to accomplish various tasks.<p>The best documents give core API references, example calls, multiple calls chained together, and the full back-and-forth HTML exchange data to see authentication and calls working.
I'd have to second the poor documentation is the biggest pain.<p>Another would be not providing sample code in whatever particular language you might be working in.<p>In terms of programming against an API, it's having to worry about handling the situations that occur when an API call fails, for example retrying later. You can't assume that the API will always be available when talking about web service type API's.