Should I use HTTP status + message body for an error, or my own set of error codes?

For example, this is a request:

    "number": 8

And these are two possible responses:

HTTP status: 400 Bad Request
    "error": "expecting an odd number"


HTTP status: 200 OK
    "success": false,
    "error": <enum value that represents the error, or a string>
  • 1
    #1 is the regular solution. #2 without success is useful when we have a wide catalog of errors. Also allow you to delegate the translation (i18n) to the client.
    – Laiv
    Commented Apr 26, 2018 at 18:33

1 Answer 1


It depends

An important thing to recognize is that the status code, as well as the headers, are metadata that has meaning to the generic components that are participating in the message exchange. They aren't really intended for the end consumer.

One of the key differences between 2xx and 4xx is the effect that it has on caches. RFC 7234 explains

A cache MUST invalidate the effective Request URI (Section 5.5 of [RFC7230]) as well as the URI(s) in the Location and Content-Location response header fields (if present) when a non-error status code is received in response to an unsafe request method.

PUT, POST, PATCH are all unsafe.

Caches (and other intermediate components) aren't supposed to go digging into the response body to figure out what is going on -- the origin server is supposed to put all of the necessary hints into the status line and headers.

So for this case, one of the dimensions of "it depends" rests on whether or not you want caches to invalidate the representations of the resource.

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.