It is not clearly stated in the API documentation nor in the auto-generated docs how to check if an API call successfully returned.

When testing the API here, for example, I made a few mistakes:

• I used a POST request instead of PATCH to update the "read" status of an object, that gave me a 405 Method Not Allowed error with an HTML document (even though I explicitely requested JSON in the URL)
• then I sent a request URL-encoded instead of JSON encoded. That gave me a 400 Bad Request, this time with a JSON document containing {"error":{"code":400,"message":"Bad Request"}} (which wasn't much more helpful)

Then I succeeded - but who knows? Should I check the JSON output to see if I get the right stuff? In this case the JSON contains only the entry (see #2817 about that) - so there's no status. Should I check the first JSON object to see if there's an error in there like I get in the 400 error?