Imagine that you are developing a front end client that will consume an API. You're working on the login page and want to display errors to users below each field, in this case you want password related errors below the password field. You submit your login information to the endpoint, the password is incorrect, and the following JSON gets returned from the server:
{ "status": 400, "message": "Incorrect password." }

How can you know which field caused this error? Sure, the error message field is useful to you as a human as you know what went wrong, but without, say, querying the message string for the word "password", you have no way to know which field this error came from in your code.

I'm trying to come up with a solution for this and wanted to get some feedback and learn standards/conventions for this sort of thing.
My solution is to add another field to the JSON response that gives an int code for each specific error, allowing the client to handle different error codes in different ways. All codes could be included in the API documentation. Other codes will exist for other errors; 002 for "username taken", 003 for "post not found", etc.

Here is an example:
{ "status": 400, "code": 001, "message": "Incorrect password." }

Alternatively, this could be simplified into something short that can be used with conditional statements:
{ "status": 400, "message": "incorrect_password" }

Used like so: if (response.message == "incorrect_password") // show error below password field

Please, let me know any obvious issues with this method and share your own methods of returning errors to the client in a way that allows them to use conditional logic based on the error.

Related post:
validation error responses in REST API

Cheers :)

  • @GregBurghardt I read that post before posting this but wasn't satisfied with the answer. I don't think our posts overlap too much. – brad Mar 16 '18 at 16:50
  • 1
    The posssible duplicate directly addresses validation errors as part of a general design. – Greg Burghardt Mar 16 '18 at 16:53
  • Additionally, an error should be attributed to one field only, or general to the entire form. Microsoft's MVC framework achieves this by making "general" errors have a key of an empty string: "" in the ModelStateDictionary object. A similar pattern could be easily used with JSON responses as well. – Greg Burghardt Mar 16 '18 at 16:55
  • And as this directly relates to a login form, you don't want to tell the end user which field is in error for security reasons. It's bad to essentially tell the user that the username is correct, but the password is wrong (so keep guessing!) – Greg Burghardt Mar 16 '18 at 16:56
  • Thanks for those comments. I'm actually using .net core mvc but opting to avoid modelState altogether, validating things myself and returning them as strings and not adding them to the modelState dictionary. Regarding security, as i commented below, my users are all visible to one another, the registration process rejects unavailable usernames and there's account lockout in place after x falied attempts. – brad Mar 16 '18 at 17:00

How can you know which field caused this error?

Make it explicit?

401  # The HTTP "Unauthorized" code is outside the JSON.
  "message": "Your credentials cannot be accepted",
  "invalid_fields": [

(The best practices suggest that you validate a login-password pair, not a single element of the pair.)

| improve this answer | |
  • Thanks for your answer. While validating them together is a nice idea, it will also decrease efficiency (and code complexity) as the API must continue while collecting errors in a list, as opposed to just stopping at the error. Granted, on the flip side this will increase the number of requests being made to the API, with users correcting their data step by step. – brad Mar 16 '18 at 16:41
  • 2
    @bradley-varol: With this idea, there is no requirement to collect all errors in the request, although it would be useful for the users. The point of validating username and password together is to avoid giving hackers information that they correctly guessed a username. – Bart van Ingen Schenau Mar 16 '18 at 16:46
  • 1
    This is a nice article regarding including multiple validation errors in a single response: kev.inburke.com/kevin/just-return-one-error – brad Mar 16 '18 at 16:53
  • 1
    Although, I find this answer great, I doubt HTTP-400 is a good reponse, since the actual request was okay. HTTP-401 should be correct according to ietf.org/rfc/rfc2616.txt – Thomas Junk Mar 16 '18 at 20:00
  • 1
    @ThomasJunk: reasonable! Updating the answer. – 9000 Mar 16 '18 at 20:08

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