Software Engineering
http error-handling http-response
Updated Sat, 24 Sep 2022 13:30:12 GMT

Error or not error?

I need to implement the following scenarios at the server:

  1. User sent too many answers in a given amount of time, for example, it can't submit more than 3 posts within an hour.
  2. User sent answer with the same text already, to prevent spamming.

My question is what is the correct way to implement client/server communication? Should the server return some kind of error, for example, 429 and 409, or return code 200 and then details of the conflict? I argue with my manager that errors should be returned. He says that error is something that we don't expect to happen, happened, but in this scenario we totally expect it.


Your manager is conflating an unexpected error with a willful refusal by the application to perform a requested action. What he says is correct about the former, but not the latter.

Anything that's not a 500 is an intentional message that is being returned by the API to the user, and therefore is not an unexpected error. The manager's statement is correct about unexpected errors, but he's mislabeling conscious refusals as if they're unexpected.

It may be a semantical issue. Since your manager seems to think "error" refers to unexpected failures, try communicating with them in their own lingo. Don't refer to conscious refusals as an "error", but rather as a "negative response" or a "rejected request". You may find them more willing to listen to you once you use the words the way they use them.

However, I cannot tell you how to convince your manager. I don't know why they're taking the stance that they are, nor if anything will be able to sway their current idea.

What I would do here is to work through your manager's example, because I suspect you can Socratically bring him to your goal. Something along the lines of:

DEV So tell me, the conflict details when we return a 200, what would they look like?
MAN Well, they should explain the reason why something failed.
DEV And this should also indicate which kind of failure happened?
MAN Yes, because this gives the requester the information they need.
DEV This means we're going to need a list of kinds of failures that could occur, so that the requester can respond appropriately to the specific kind of failure that was encountered.
MAN Yes.

At this point, you can showcase that this is precisely what HTTP status codes are built to do. The message that's being returned can always be chosen as you please; but the HTTP status code that you attach to this message is simply a standardized "kind of failure" that helps the requester quickly categorize what kind of failure was encountered (Did it work? Was it my fault? Was is the API's fault? Was I not allowed to access this endpoint? ...)

We made a universally agreed upon list of codes that everyone uses, so that everyone who can write software doesn't have to learn every API's own custom error codes, because it'd be an unnecessary hassle to express the same kinds of failures in individually unique ways.

If your manager still doesn't budge; maybe try asking them for information on their solution. Why would the arbitrary "failure code" be better than the universal HTTP status code? What would happen differently if you instead used the HTTP status code?
Listen to your manager, understand their reasoning, try to explain why you can achieve the same goal using the more standardized HTTP status codes.

But I want to reiterate that I cannot guarantee that your manager is willing to listen to your input, or that they even have a reason for their choice (they may be parroting existing knowledge with no intent to have it be put under a microscope). Good luck.