title: Public API design - handling failure with a http code? Is that REST?
body: <p>I am just about to make a webservice available for fellow programmers in my sector using PHP on my own server. </p>
  
  <p>As this is the first time I have done this, I first investigated APIs that I frequently use, Flickr etc.</p>
  
  <p>My service returns granular data extracted from a very large csv file by examining GET arguments, it is read-only.</p>
  
  <p>The data is returned in a variety of formats, xml, json, jsonp etc.</p>
  
  <p>example of the call: /?offices=ABC|XYZ&amp;format=xml</p>
  
  <p>Firstly, I'd like to know if I am I correct in terming my service an "API"?</p>
  
  <p>Also I would also like to know how best to handle failure.</p>
  
  <p>I return straight text messages in the case of a user not submitting the expected input - "you failed to submit any offices".</p>
  
  <p>In the case of any other unforeseen malfunction, at the moment it returns a failure message in payload of the chosen format, eg json with the single array "fail" in it and I have documented this.</p>
  
  <p>Having read up a little on REST recently, when a failure is not caused by misuse of the "API" - should I return something other than HTTP code 200?</p>
  
  <p>If you were accessing this service, what would you prefer to see?</p>
  
  <p>Should I make this another GET option?</p>
  
  <p>e.g /?offices=ABC|XYZ&amp;format=xml&amp;on_failure=http</p>
  
  <p>Or am I getting muddled between the terms API and REST?</p>
  
  <p>SO suggested this post, which deals with 400/401 </p>
  
  <p><a href="https://stackoverflow.com/questions/1959947/whats-an-appropriate-http-status-code-to-return-by-a-rest-api-service-for-a-vali">What&#39;s an appropriate HTTP status code to return by a REST API service for a validation failure?</a></p>
  
  <p>but I am looking for clarification about the terms I am using.  If the payload contains the error message - as in the case of Flickr then why should I wander away from that?</p>