Valid

HTTP response validation

Required: no Default: true

This directive lets you decide whether the HTTP response returned by a service is valid or not. If this directive is not present, the response is considered always valid when the status code is between 200 and 399 (inclusive).

Some services might return an HTTP status code >= 400 if there is an error. These are handled by standard error handling. But some services might return an HTTP status code < 400 (mostly the HTTP 200) and indicate an error in the response body or headers. In that case, it makes no sense to output anything from the module, but instead indicate that there is an error.

Behavior

• If the valid directive evaluates to a false value (false, undefined, null, etc.), module execution stops and Make throws an error. The execution log will display either your custom error message or a fallback message.

• If the valid directive resolves to a truthy value, the module will continue execution normally.

Basic usage examples

Both of the following forms are equivalent. You can define valid as as simple condition (valid": "{{!body.error}}) or as an object within a condition property plus optional message and type.

Example 1

{
    "response": {
        "valid": {
            "condition": "{{!body.error}}"
            // Causes error 'Response marked as invalid.' if `error` property exists in HTTP json response body.
        }
    }
}

Example 2

Custom error message

It is also possible to define an expected error message in this way:

Custom error message

{
    "response": {
        "valid": {
            "condition": "{{!body.error}}",
            "message": "Service returned HTTP {{statusCode}} with error: {{body.error}}",
            "type": "UnknownError" // `RuntimeError` is the default, if type is not specified
        }
    }
}

If no type is specified, the default RuntimeError is used. In the example above, setting "type": "UnknownError" overrides this default.

Fallback error messages

Fallback error message

{
    "response": {
            "valid": {
                "condition": "{{body.status != 'error'}}"
                // `message` not specified here, so fallback to `response.error.200` is used
            },
            "error": {
                "200": {
                    "message": "Service returned error: {{body.message}}"
                }
            }
        }
}

The response.error.<statusCode> directive is used as a fallback if valid.message is not specified.

Source

{
    "response": {
            "valid": {
                "condition": "{{body.status != 'error'}}"
                // `message` not specified here, so `response.error.200` is tried as fallback
            },
            // `200: {...}` code specific error directive also not specified, so generic `response.error` is used as fallback
            "error": {
                "message": "Service returned invalid status '{{body.status}}'."
            }
        }
}

The response.error directive is used as a fallback if valid.message and response.error.<statusCode> are not specified.

The priority of error message resolution is as follows. The first matching is used, the rest are ignored.

1. Directive response.valid.message

2. Directive response.error.<statusCode>.message

3. Directive response.error.message

4. Static message: Response marked as invalid.

Error type resolution

The priority of error type resolution is the same as for error message above:

1. Directive response.valid.type

2. Directive response.error.<statusCode>.type

3. Directive response.error.type

4. Default type: RuntimeError