I'm looking for guidance on best practices for returning errors from a REST API. Currently, I'm working on a new API and have the flexibility to choose the right approach. Currently, my content type is XML, but I plan to support JSON in the future.
I'm in the process of adding error cases, such as when a client exceeds their storage quota while trying to add a new resource. I'm already handling certain error cases with HTTP status codes (401 for authentication, 403 for authorization, and 404 for invalid request URIs). However, I've reviewed the recommended HTTP error codes, and none of the codes in the 400-417 range seem appropriate for reporting application-specific errors.
Initially, I was tempted to return my application error with a 200 OK status code and a specific XML payload (e.g., "Pay us more and you'll get the storage you need!"). But upon further consideration, I realized this approach might be problematic and confusing. It feels like I would be splitting the error responses into separate cases, with some driven by HTTP status codes and others by content.
Therefore, I would like to know the industry recommendations for good practices in this area. It would be helpful if you could explain the reasoning behind these recommendations. Additionally, from a client perspective, what kind of error handling in the REST API would make life easier for the client code?