Develop error handling for microservices

[tschaffter]

We have a schema for the error but the microservices are not implementing it. This schema was derived from RFC 7807.

Since then we adopted a microservice architecture. One of the error design proposed here is to add a global error code to the error object that enables to identify the microservice that reported the issue.

One important piece of information missing from our error schema is a timestamp.

Two fields that should be defined together in the RFC 7807 are the title and status as highlighted in the following Java example from zalando/problem-spring-web:

       return Problem.builder()
                      .withTitle(status.getReasonPhrase())
                      .withStatus(status)
                      .withDetail(exception.getMessage())
                      .with("parameter", exception.getParameterName());

Here are error schemas used by GitHub:

    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
    validation-error-simple:
      title: Validation Error Simple
      description: Validation Error Simple
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
        documentation_url:
          type: string
        errors:
          type: array
          items:
            type: string

Questions

• Should we expose microservice error code to the user?
• Should we work with an internal (private) and user-facing (public) error objects?
• Shall we return application/problem+json responses instead of application/json?
  • Ideally yes. See this medium article.

[tschaffter]

This is our current schemas:

  title:
    type: string
    description: A human readable documentation for the problem type
  status:
    type: integer
    description: The HTTP status code
  detail:
    type: string
    description: A human readable explanation specific to this occurrence of
      the problem
  type:
    type: string
    description: An absolute URI that identifies the problem type

Notes:

• The property title and status should ideally be defined together.
• The property detail should include resource object-specific information (e.g. "Challenge with ID 123 not found").
• The property type could be used to capture the microservice error code if we decide to return it to the user. This may provide information about the underlying architecture that we don't necessarily want to expose to the user. This information may also be difficult to document for the same reason.

[tschaffter]

~Spring Boost~ OpenAPI generator does not seem to support the MIME type application/problem+json?

  default ResponseEntity<OrganizationDto> getOrganization(Long organizationId) {
    getRequest()
        .ifPresent(
            request -> {
              for (MediaType mediaType : MediaType.parseMediaTypes(request.getHeader("Accept"))) {
                if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
                  String exampleString = "{ \"name\" : \"DREAM\" }";
                  ApiUtil.setExampleResponse(request, "application/json", exampleString);
                  break;
                }
                if (mediaType.isCompatibleWith(MediaType.valueOf("application/problem+json"))) {
                  String exampleString =
                      "Custom MIME type example not yet supported: application/problem+json";
                  ApiUtil.setExampleResponse(request, "application/problem+json", exampleString);
                  break;
                }
              }
            });
    return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
  }