Message vs ErrorMessage API design

Question

I'm desing API for generic task executor that currently supports two calls:

1. Accept task
2. Get task info

The (2) provides detailed information about the task with the task status and custom message, for example in JSON format:

{
 ...
 status: "SUCCESS",
 message: "The task has been finished successfully"
 ...
}

In case of status "ERROR" do I need to have a separate field "errorMessage" or it's normal to write error message to field "message"? Technically any solution is possible, but I'm looking for the best practices, I didn't find any strict recommendations yet.

• Dunk: It kind of depends on how you plan on using the message, but generally when I do something like you want, I simply have a status and errorText field. If status is SUCCESS then there's no reason to fill in the message/errorText field. Saying the task finished successfully is redundant.
• erkfel: @Dunk I'm personally not planning to use it, but other people are going to use that API, that is why I'm interested about the best practice/expectation here. I like the idea to keep the errorText and just leave it empty in case there is nothing to report there, thanks !

Answer 1

...do I need to have a separate field "errorMessage"?

Only if you need to maintain two separate messages in any given JSON transaction.

• erkfel: I don't need to have two messages, I just need to provide more information what happened with the task, either successful or not successful.
• Robert Harvey: Then it's one transaction, one message, one field.

Answer 2

You'll get more mileage with a status/message pair than with a separate errorMessage property. For instance, if you wanted to write a general 'alert' function showing the job and its status, it will be a cleaner piece of code to use the status to determine colour, and always show the same 'message' property.