Say I have a lot of page with ajax. Is there any convention or recommendation on the format/structure of an ajax response? Namely, if there's an error, a server returns http status 4xx or 5xx and... what structure should a json response have? Should it be with the root-level key "errors"? What structure should an an item of "error" have? Or should there be a simple array of errors? What if there was a single error?

The same goes for a successful response: should there be a root-node "data", for example? And so on.

I'm aware about jsonapi.org, for example, but it's for public REST APIs, whereas I use ajax only across my website and therefore probably I'm the only user and it should be simpler. Although, yes, possibly it can be used from other websites as well by other users.

  • en.wikipedia.org/wiki/JSON-RPC
    – Idan Arye
    Apr 20, 2017 at 9:00
  • @IdanArye, what does ajax have to do with that? and why, only because you think they're related? moreover, what if I use xml for ajax?
    – Dorion
    Apr 20, 2017 at 9:02
  • You asked for a format for the server response. JRPC-RPC is such a format, and it's relatively simple and well supported. If you used XML you could have used XML-RPC
    – Idan Arye
    Apr 20, 2017 at 16:09
  • @IdanArye, JSON-RPC is not such a format. JSON-RPC is a format for RPC.
    – Dorion
    Apr 20, 2017 at 23:34

1 Answer 1


Asynchronous JavaScript and XML has largely been abandoned in favour of JSON and 'REST' although full REST is rarely implemented.

This means sending error codes in the HTML response code and a plain text message in the body as you would see with a normal failed HTTP request.

This has several downsides, control flow by exception, ambiguous error codes. But the advantage of being simple and not complicating your response object with a possible error state.

Where you have a complex, not success, result to return such as input validation, I suggest structuring your return object to specifically include those results as a success rather than attempt to cram them into an error message. eg

HTTP 200
        "validationMessages" : [
            "username already in use",
            "password must contain at least one capital letter"

You can see this object works equally well for both success and failure, leaving the HTTP code for 'real' exceptions where the code errors or the server fails in some way

  • my question isn't what one would suggest me, but what's the most commonly used, even if there's no official standard for it. what's your advice based on? who else follows this approach? moreover, "validationMessages" is a very specific case of an error, there're even no names of the fields and it's not right, it should better contain an object or array of objects instead of just string.
    – Dorion
    Apr 21, 2017 at 8:02
  • well I have provided both. the published (and popular) standard (REST) and what I consider from my experience to be a good solution to the 'complex error' case (with simple example) which is not well served by the standard
    – Ewan
    Apr 21, 2017 at 8:07
  • because its a success response, the object is defined by your api rather than the protocol, so you can define specific responses for each endpoint
    – Ewan
    Apr 21, 2017 at 8:08
  • This means sending error codes in the HTML response code --> this also means that an http response status shouldn't be 2xx in case of an error.
    – Dorion
    Apr 21, 2017 at 8:09
  • yes, but you get to define what an 'error' is. so where your api has a complex response, define it as a successful api call which returns the structured response saying what the result of that call was. in this case, we didnt add the user because of x,y, z
    – Ewan
    Apr 21, 2017 at 8:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.