Best Practices for Errors and Warnings

[Jeremy R]

I'm trying to get a sense of best practices for communicating errors and warnings for API calls. I've had one person tell me that the best way is to return detailed information in the body (the spec indicates that on a 400 the body should contain an entity with detailed information). Another person is telling me that he's found that today it is vastly preferred to use the warning header.

Personally, I'm not seeing a lot of evidence that industry is moving (or has moved to) the warning header, and I'm concerned that it doesn't allow for detailed information--just a 3 digit number and a string. My current planned compromise is to use the warning header to specify generic error conditions but continue to put detailed error information in the body. The detail I'm wanting to communicate is the element(s) of the request that caused the failure.

My question is this: Has the use of the warning header become the standard for things other than caching? And has your experience shown whether having a more detailed error entity in the body has been useful?

Thanks,

Jeremy

[Chris Mullins]

I've actually never heard of this before. That it's "vastly preferred" is very much news to me. Do you have examples or links you can share of this being used? 

As a general rule, I recommend the ODataV4 approach (even if you're not using OData), as it's quite good, broadly supported, and well thought through. 

You can find it documented here:

http://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html#_Toc372793091

Cheers,

Chris

[Andrew Braae]

May be worth looking at Mark Nottingham's approach https://www.mnot.net/blog/2013/05/15/http_problem.

[Thomas Lörcher]

Thanks for the hint. Will be pretty useful!