Also return a json with an error when something went wrong with a call and separate the self-documentation part out to avoid mixing them up. No dev wants to get a html page when they expected JSON...
TomZ