Standardized error codes for "known" errors

[narve]

Define a list of error codes that will cover the known and expected errors that can occur.

[narve]

Also specify how errors are transmitted (e.g. refer to the "problem details" RFC etc)

[cdmNSIDE]

For me the solution (and the convention I think) is to use a 400 "invalid input" and to add in the body of the response a description of the error, in JSON format

[narve]

Yes, but that is only the start of it. We should also describe the body. It should follow the "problem details" RFC, which means that it should have a "type" property. This type property should have a fixed list of values, e.g. "InvalidGridNode". This will enable the error handling to be as uniform as possible across FMOs.

[narve]

Some examples of possible error codes: InvalidGridNode, InvalidMarket, MarketClosed, OrderPeriodClosed, OrderPeriodNotYetOpen, etc.

[narve]

The idea here is that common errors, the ones defined by UEMI, can be handled uniformly across FMOs.

There will of course be other errors, FMO-specific, that can not be handled uniformly across FMOs. That is unavoidable, but it is nice if the common errors are reported the same way for different FMOs. This will make error handling quite a lot easier.

[cdmNSIDE]

Hello Narve,

I fully agree with you. I think the next steps are:

1. Agree on a format for the "functional errors", i.e. errors that are automatically detected by the API (for instance when a field is a negative number while only positive values are allowed). In that case I think we can create only one error common error template that will be applicable for all those errors.
2. Agree on a format for the "business errors", i.e. errors that will be triggered by an invalid input check performed by the market platform. In that case, I think the body of response request should contain at least the code of the error, a message to describe the error, and (optionally) some details about this error.
3. Prepare a list of all "business errors" that we would like to handle

[cdmNSIDE]

For the "functional errors", we could do something similar to:

responses:
    '400':
      $ref: "../openapi.yaml#/components/responses/InvalidInput"

InvalidInput:
      description: The input data does not respect the API specification.
      content:
        application/json:
          schema:
            $ref: 'RequestErrorReport.yaml'

With RequestErrorReport.yaml containing:

type: object
description: Report of the error
required:
  - message
properties:
  message:
    type: string
    description: Description of en error
    example: "The request is not compliant with the API specifications"
  details:
    type: array
    description: List of detected violations of the API specifications
    items:
      $ref: 'SpecificationViolation.yaml'

And SpecificationViolation.yaml being:

type: object
required:
  - property
  - message
properties:
  property:
    type: string
    description: Path of the invalid json property
    example: "start.arg0.order[1].power"
  message:
    type: string
    description: Description of the issue with this property
    example: "must be greater than or equal to 0.0"
  value:
    type: string
    description: Value received as input for this property
    example: "-5"

We could also explicitly write at which line of the input the error is located

[narve]

This seems like a very nice starting point. However, given that there is a standard for this, I propose modifying the protocol that you proposed so that it conforms to that standard. Many server- and client-frameworks already have built in support for this standard.

Please have a look at https://datatracker.ietf.org/doc/html/rfc7807

So I propose something along the same lines, adapted to that protocol. What do you think, @cdmNSIDE ?

[cdmNSIDE]

Thanks for pointing that out! Indeed if there is a protocol it's better to stick to it. Would you use it only for the "functional errors" or also for the "business errors" (see my comment above for the explanation about the distinction between those errors) ?

[narve]

I would use it for both, yes. However, the shape of the "details"-element could possibly be different for different errors.

[narve]

See #40 . Suggest we close this issue when that PR is merged. Adding common error codes will be an ongoing process.