Successful requests. Sometimes when you encounter failures, it can feel like the server has a vendetta against you. But take heart, the server simply isn't smart enough to recognize your request and behave differently. Most likely your request has some minor issue that prevents the server from handling it correctly. Your very best strategy for figuring out why a request isn't working is to use the tools provided by the API team itself -- consoles, sample code, test tools -- to see what a successful request looks like. For instance, Mashery provides IO/Docs, an interactive explorer, for USA Today and the other APIs it hosts. Similarly, Apigee has a console for Twitter and many other APIs. Both tools give you the ability to see successful calls without writing any code. Check out the headers, URL, and body of those requests; if you can make your request match it's going to succeed.
4XX errors. If the response you receive is a 4xx error, your request isn't what the server is expecting to see. Here's a quick rundown of what these specific codes mean.
- 400: Formatting error. Your headers, parameters, or POST body are not formatted correctly. You may be missing a required parameter or you have added an unexpected one. The response body should have information that will help you spot the misstep.
- 401: Authentication error. The server doesn't recognize something about the authentication you're using. Your signature may not match, or the token may be invalid. Again, check the response body for helpful clues. If you're lucky, the API team has made tools available that will allow you to check your authentication and work through the issue.
- 403: Authorization error. The server knows who you (and your user) are, but you aren't allowed to see the resource. Sometimes this is a permission issue (restricted to certain users). But if you start seeing 403 errors after successful requests of the same type, then most likely you're being throttled (so you're no longer allowed to access that resource). Review the throttle limits for the API, and remember that throttles are frequently different for an application as a whole as opposed to specific users of an application.
- 404: Not found. The resource you requested isn't a valid path. We all know what this means.
Asking good questions. Most APIs have documentation, forums, and other resources available to help you achieve success. However, if you're not able to solve the problem on your own, you'll want to ask for help on a forum -- either one devoted to the specific API or a good general-purpose developer's venue like StackOverflow. Technical questions asked without enough context can kick off a frustrating cycle of exploratory questions, guesses, and clarifications, delaying the resolution of your issue.