500 Internal Server Error: OpenAPI Response Validation Failed

Membrane API Gateway returns 500 Internal Server Error with the title OpenAPI message validation failed when response validation is on and the backend response does not conform to the OpenAPI document. The backend is to blame, not the client, and the client receives this error instead of the backend response.

The Error Response

The response contains the status 500 Internal Server Error, the title OpenAPI message validation failed, a validation field that lists the errors, the problem type https://membrane-api.io/problems/user/validation and a link to this page. The type user/validation means that a message did not pass validation. Because the error happens in the response flow, the status is always 500. In production mode, the title is replaced by Internal Server Error and the type is shortened to https://membrane-api.io/problems/user.

How OpenAPI Response Validation Works

With validateResponses on, Membrane checks every backend response against the response definitions of the operation in the OpenAPI document: the status code, the content type and the body schema. This makes sure that clients only receive responses that match the published contract. See OpenAPI Configuration and Validation.

api:
  port: 2000
  openapi:
    - location: fruitshop-api.yml
      validateResponses: true

api:
  port: 2000
  openapi:
    - location: fruitshop-api.yml
      validateResponses: true

Common Causes

An Undocumented Status Code

The backend returns a status that the operation does not describe, for example a 500 or 404 error response when the document only lists 200.

An Undocumented Content Type

The backend returns a Content-Type that is not listed for the status, for example text/html instead of application/json.

The Body Does Not Match the Schema

The body lacks a required property, has a property with the wrong type or format, or contains properties the schema does not allow. This often happens after a backend change that was not reflected in the document.

How to Fix It

1. Read the validation field of the response. Each entry names the location of the error and the violated constraint.
2. Decide whether the backend or the document is wrong.
3. Fix the backend so that it returns documented responses, or update the OpenAPI document, including the error responses the backend can return.

While you fix the mismatch, you can switch response validation off with validateResponses: false.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. In production mode, the link to this page is left out:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---. The list of violations in the validation field is still sent in production mode, because it describes the message against the published API. To leave it out, set validationDetails: false on the openapi entry:

api:
  port: 2000
  openapi:
    - location: fruitshop-api.yml
      validateRequests: true
      validationDetails: false

api:
  port: 2000
  openapi:
    - location: fruitshop-api.yml
      validateRequests: true
      validationDetails: false

Related Documentation

Configuration reference:

• openapiValidator
• openapi

Tutorials with runnable examples:

• OpenAPI Validation
• OpenAPI

← All Membrane error messages