Error Codes

[honzajavorek]

I think there should be a dedicated optional field for "error code", i.e. error's unique identifier within given application. Client could then implement it's own logic how to react in certain error situations. Without error codes, it can only parse error messages, which doesn't seem very optimal to me.

[fidian]

Agreed, though I would call it "code" because the spec says "message" instead of "error message".

I write code against codes. Having this added as a part of the spec gives additional semantic information about the usage of "code" and that programmers will know they can rely on the code being returned again in the future for problems of this type. Plus then I am able to get a list of codes and generate my own translation of each message for sites where an API response should be displayed in a different language.

[honzajavorek]

:+1: I agree, also with the code naming. Makes sense.

[mjallday]

We made a similar extension but called it category_code. This has, in our experience, been the easiest way to programmatically consume these errors.

Here's a json schema that validates it.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "logref": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "_links": {
      "properties": {
        "source": {
          "$ref": "link.json"
        }
      },
      "type": "object"
    },
    "category_code": {
      "enum": [ "NOT_FOUND", "UNKNOWN", "CONFLICT", "BAD_REQUEST" ]
    }
  },
  "required": [
    "logref",
    "message",
    "_links",
    "category_code"
  ],
  "additionalProperties": true
}

[honzajavorek]

The problem I see with category_code is that so far vnd.error doesn't prescribe any naming convention (camelCase, under_score) and I think it would be nice to keep it like that, so anyone is encouraged to adopt the format.

[fidian]

I would also want a specific error, not a category. My application could have thousands of reportable errors. I may prefix them like "upstream.e82n" or "db.001i" to categorize them. Each code would report a specific thing so my application could retry or wait a bit or maybe prompt the user to determine what to do next.

[ZhukV]

+1, but:

Problem

The code of error is bad for understanding between developers. The developer should know about all codes or see the list of available codes in each time for correct control this error (if resolved by code).

As example

We receive the error with code 155.

{
    "message": "Operation not allowed.",
    "code": 155
}

What is 155? We should open the documentation about all error codes and search this code for understand error.

Yes, the developer can make the correct messages, but many systems (and I too) want to resolve and control all errors by code (as an example: run custom logic for each error).

Solution

Maybe better add the reason parameter? This parameter must be a string as constant and the developer after reading the reason can understand the error.

As example:

{
    "message": "Operation not allowed.",
    "reason": "PaymentIsDissabled"
}

[fidian]

@ZhukV I am totally in favor of using a unique string for a code. 155 means nothing to me either, but PaymentIsDisabled also doesn't tell me if it is a permanent error with this transaction, nor does it inform me if this error code is likely to show up during my user journeys and I should handle this one specially.

It looks like your reason could just as well be used as a code because code allows for an alphanumeric string. I would suggest code is a better name for the attribute because I would expect reason to be a string I could present to an end user. With it being treated as a code, I still need to implement a lookup table on my side and translate "PaymentIsDisabled" into "Sorry, but payment is disabled at this time. Please try again later. We're sorry for the inconvenience."

[honzajavorek]

@ZhukV Sounds great to me. I also tend to incline to @fidian's suggestion about code, as it seems to be more versatile to me. Imagine there are legacy systems where you just can't get rid of numeric codes. Having code as alpha-numeric identifier works for all scenarios I can come up with.