I'd have to second the poor documentation is the biggest pain. Another would be not providing sample code in whatever particular language you might be working

I'd have to second the poor documentation is the biggest pain. Another would be not providing sample code in whatever particular language you might be working in. 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.