Why does Membrane return 500 Error parsing JSON?

The json2Xml plugin could not convert a message into XML because its body is declared as JSON but is not valid JSON, or because the body could not be read. The flow field of the response says whether the request or the response was affected.

How can I reject invalid client JSON with 400 instead of 500?

Validate the request before json2Xml, for example with the openapi plugin or with a validator that uses a JSON schema. Invalid requests are then rejected with a 4xx before the conversion runs.

How do I hide the details in Membrane error responses?

Enable production mode by adding a configuration document with production: true to your apis.yaml. Membrane then leaves out detailed information, such as the exception message and the link to the documentation, from error responses.

500 Internal Server Error: Error Parsing JSON

Membrane API Gateway returns 500 Internal Server Error with the title Error parsing JSON when the json2Xml plugin cannot convert a JSON message into XML. The message is labeled as JSON, but its body cannot be parsed.

The Error Response

The response contains the status 500 Internal Server Error, the title Error parsing JSON, the message of the JSON parser, the problem type https://membrane-api.io/problems/internal/validation/json and a link to this page. The type means that the gateway failed while processing a JSON message. The flow field says whether the request or the response was affected, and in development mode the body field shows the first 200 characters of the body. In production mode, the title is replaced by Internal Server Error, the type is shortened to https://membrane-api.io/problems/internal, and the details are left out.

The status is 500 in both flows. If the request flow fails, the client sent the invalid body. If the response flow fails, the backend did.

What the json2Xml Plugin Does

The json2Xml plugin converts message bodies with a JSON Content-Type, such as application/json, into XML, for example to send a JSON request to an XML or SOAP backend. Messages without a JSON content type are passed on unchanged.

Common Causes

The Body Is Not Valid JSON

The body is declared as JSON but is truncated, contains a syntax error such as a trailing comma, or is not JSON at all. The message of the JSON parser in the response shows the position of the error.

The Body Cannot Be Read

The body cannot be read or decoded, for example because the Content-Encoding header is wrong or the sender aborted the transfer.

How to Fix It

Client side (request flow): send valid JSON, or do not use a JSON Content-Type for content that is not JSON.
Backend (response flow): make the backend return valid JSON, or label responses that are not JSON correctly.
Gateway operator: to reject invalid client JSON with a 4xx instead of this 500, validate the request before json2Xml, for example with OpenAPI validation or with a validator that uses a JSON schema.

A validator in the request flow checks the JSON before the conversion runs:

api:
  port: 2000
  flow:
    - request:
        - validator:
            jsonSchema: order.schema.json
        # json2Xml goes here, after the validator
  target:
    url: https://api.predic8.de

api:
  port: 2000
  flow:
    - request:
        - validator:
            jsonSchema: order.schema.json
        # json2Xml goes here, after the validator
  target:
    url: https://api.predic8.de

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---. The title then reads Internal Server Error, and the details and the link to this page are left out. If the response contains a log key, search the gateway log for it to find the full error message.