Schemas in error responses

[jlurien]

In the different WGs we have 2 approaches to specify the schema for error responses:

1) Reference to the common ErrorInfo model:

components:
  schemas:
    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string
  responses:
    Error400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 400
            code: INVALID_INPUT
            message: "Schema validation failed at  ..."

2) Reference to the specific model for the status and code:

components:
  schemas:
    Error400:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          enum:
            - 400
        code:
          type: string
          enum:
            - INVALID_INPUT
        message:
          type: string
  responses:
    Error400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error400"
          example:
            status: 400
            code: INVALID_INPUT
            message: "Schema validation failed at  ..."

In the second case there is a strict specification that for certain error response the status and code values must be the one in the enum, while in the first case, we are relying on examples and external doc to guide implementations. On the other hand, the first approach is more simple and it may ease the code generation as schema model is reused.

It would be convenient to define a global guideline son all APIs follow the same approach.

[sfnuser]

If it is not too late, perhaps we could also explore RFC 7807 to define Error Info as ProblemDetails. This provides a format that will be uniform across APIs and each API can extend or provide detailed scenario examples as appropriate.

[eric-murray]

My preference is option 1 (common ErrorInfo schema with specific examples). For most clients, that should be enough information.

In my experience, it is rare for a client to implement any sort of logic to automatically recover from errors, other than to try again with the same request (for any timeout or not available error), or to refresh the OAuth token if that has expired. Otherwise, the operation fails and the error gets logged. And then somebody may investigate if it keeps happening.

[RubenBG7]

Common model errors defined and consensuated in CAMARA API Guidelines, are focused on make the same error logic in all APIs implementations in all Telcos involved.

ErrorInfo Schema is defined to be enriched by the specific error types.

Totally Agree with @jlurien

[shilpa-padgaonkar]

My preference is for approach 1

[patrice-conil]

My preference is also for approach 1.

[GuyVidal]

Approach 1 is more simple, my preference

[RubenBG7]

Changes applied on PR #162

[jlurien]

As we got an agreement on this issue (refer to common ErrorInfo model), I proceed to close it. Thanks to all for your valuable feedback.