Guidance on error responses - are error messages standardized or can they be custom?

[trehman-gsma]

Problem description
This is related to error responses within the API design guidelines.

An example of a JSON error response structure is below:

{
   "status": 400,
   "code": "INVALID_ARGUMENT",
   "message": "A human readable description of what the event represents"
}

I understand that the status values and code values are standardized. Is there guidance on the message value - can it be a custom per Operator?

To elaborate, please consider this example error response from the SimSwap YAML for the scenario where an input phone number cannot be found:

{
   "status": 404,
   "code": "SIM_SWAP.UNKNOWN_PHONE_NUMBER",
   "message": "SIM Swap can't be checked because the phone number is unknown."
}

I assume that for this specific scenario, all Operators must align with the same status value (404) and the same code value (SIM_SWAP.UNKNOWN_PHONE_NUMBER). For the message value, can each Operator provide a custom human readable message or must they align with the error message provided in the YAML for the specific scenario?

Possible evolution
A paragraph within the Error Responses section of API design guidelines documenting the group view on error messages.

[bigludo7]

Hi @trehman-gsma
+1 on the requirement to clarify this.

my 2cents:

• status as specified in the document MUST be a standard code from a list of Hypertext Transfer Protocol (HTTP) response status codes so this one is NORMATIVE
• code - the guideline is not normative but provide table with value. My understanding is that if a working group or an implementation has to manage this case, they could use this code (eg. if you want throw back an error if Either out of resource quota or reaching rate limiting then it must be TOO_MANY_REQUESTS code). But, I tend to think that code in the YAML of a given API are normative. So conformance rules should be something like: an implementation has to provide the code defined in the YAML. Additionally, it is possible to add other code for distinct case not cover in the YAML and in this case it is strongly recommended to use code from the DG tables.
• message - Probably we can specify that it is recommended in implementation to use examples provided in the YAML but I do not think we can enforce anything for conformance perspective.

[rartych]

@trehman-gsma Thank you for raising this issue.
The discussion started in Issue #31 but without conclusion.

As RFC 9457 Problem Details for HTTP APIs was published this year we can think of using "Problem JSON" in CAMARA the same way as CloudEvents format was introduced.
This RFC is very new so the view of developers (API producers and API consumers) would be helpful.

[akoshunyadi]

I would prefer standardized error objects too. But also over multiple APIs. So e.g. there could be one UNKNOWN_PHONENUMBER which could be reused in multiple APIs.
So all the fields status/code/message would be the same at all operators, and if possible all APIs, like a global error list.

Using very specific attributes, like in the RFC, I think it's difficult to evaluate. But the idea of global types ("type": "https://example.com/probs/out-of-credit") I would support.

[gmuratk]

I was working towards some suggestions to #31, which is referenced above, so instead I’ll post it here.
While we are still waiting on the EUC feedback/input, I’d here are some suggestions:
(Note: I’ve used the QoD API (v0.10.0-rc) as an example API definition for some of these observations and suggestions.)

1. Current responses make use of the ErrorInfo schema defined which has a property named ‘code’. I'll argue that ‘code’ could be misleading to a developer, especially given the fact the defined ‘code’s deviate from the HTTP Status Codes defined in RFC 9110 (e.g. 400 Bad Request -> Invalid Argument, 401 Unauthorized -> Unauthenticated, 403 Forbidden -> Permission Denied, 500 Internal Server Error -> Internal, 503 Service Unavailable -> Unavailable)
2. As it was previously suggested in Adopt RFC 7807 error responses to allow API consumers to be reminded of the API definition #31, instead of ErrorInfo schema we can use a the ProblemDetails for HTTP APIs a. However, given RFC 7807 is obsoleted by RFC 9457, so we should consider the newest RFC.
3. A suggested mapping of properties between ErrorInfo and ProblemDetails can be (status => status, code => title, message => detail).
4. ProblemDetails can be extended, like 3GPP TS 29.571 CommonData.yaml, with a new property ‘cause’. This field can be designated as ‘machine-readable’, in other words, actionable by receiving software/application, to pass a specific cause to the occurrence of the problem. For each API, there will be a specific list of ‘causes’ that can be defined in the YAML.
5. The recent discussion in Device Status Multi-Operator Demo Test Discussion · camaraproject/DeviceStatus · Discussion #89 (github.com), shows that there may be need to describe the use cases to align on the error codes for a given API.
6. In each API specification ApiSpecificErrorCauses schema can be described as an array of enums to list all the application specific causes and these can be described. This will alleviate the need for use of the ‘type’ field of the ProblemDetails url to point to a specification URL (see Adopt RFC 7807 error responses to allow API consumers to be reminded of the API definition #31 for some concerns that were raised). Error causes that are common across multiple APIs can be listed in the CAMARA_common.yaml and they can be replicated as necessary in each API specification as well.
7. In alignment with Update and rename CAMARA_common.json to CAMARA_common.yaml #107 HTTP responses should be moved to the CAMARA_common.yaml, ProblemDetails schema can be defined in the CAMARA_common.yaml. Note: Using the CAMARA_common.yaml for the responses reduces the number of lines in the [QoD] API and unnecessary repetition.

An example of the modified QoD API (forked from v0.10.0-rc) that is making use of an example CAMARA_common.yaml can be found in the following link: https://github.com/gmuratk/QualityOnDemand-httpresponses/blob/main/code/API_definitions/qod-api.yaml

[akoshunyadi]

@gmuratk I think it would be better to continue this discussion about adopting RFC7807/9457 in #31 because there are already important arguments.

[rartych]

Discussed in further issues