In-Flight Masking Troubleshooting

This guide helps you diagnose and resolve common issues when using DataMasque's in-flight masking service. For each problem, you'll find a clear description and specific steps to resolve it. If you cannot resolve an issue using this guide, please contact DataMasque support.

• Excessive Memory Used
• 401 Unauthorized Responses Received
• 402 Payment Required Responses Received
• 403 Forbidden Responses Received
• 404 Not Found Responses Received
• 429 Too Many Requests Responses Received
• Other Error Responses Received

Excessive Memory Used

Problem

DataMasque's in-flight masking container is using more memory than expected.

Solution

Review memory usage guide

The amount of memory the in-flight masking service uses is dependent on the complexity and count of loaded rulesets, and number of workers. Refer to the sizing guide for more information on how to calculate expected memory usage.

To reduce memory usage, unused ruleset plans can be deleted.

401 Unauthorized Responses Received

Problem

Requests receive an "Unauthorized" response with 401 status code.

Solution

A refresh token was sent instead of an access token

The detail is Invalid token: a refresh token cannot be used here. In-flight masking requests take the access_token from POST /api/auth/jwt/login/ or POST /api/auth/jwt/refresh/. The refresh_token is only for obtaining a new access token.

The token is otherwise invalid

An expired token, or one signed with a different key, is also refused. Log in again to obtain a new access token.

402 Payment Required Responses Received

Problem

Requests that should return a normal response receive a "Payment Required" response with 402 status code.

Solution

DataMasque license is not valid

Upload a valid license through the DataMasque dashboard. License data is embedded in JWTs, so after uploading a new license you must log in or refresh the JWT for the license change to take effect.

In-Flight Masking is available on Enterprise, Premium Trial and Sandbox licenses only; it is not available on Free Trial, Foundation, Structured or other license types. A Sandbox license is limited to 6 mask requests per minute, see Sandbox license. On Foundation, Structured and Ready To Run, the page opens the upgrade prompt. Other license types without In-Flight Masking can still reach the page, but a run or endpoint change is refused.

403 Forbidden Responses Received

Problem

Requests that should return a normal response receive a "Forbidden" response with 403 status code.

Solution

Role not allowed for URL

An overview of which roles are allowed to perform which actions is listed on the Authentication and Permissions documentation. Further, the documentation for each API endpoint contains the exact roles required.

Once a user's role has been updated using the DataMasque dashboard, a new JWT must be generated for the user, as the roles are embedded in the JWT.

License type does not include In-Flight Masking

Creating, updating or deleting an endpoint from the web UI is refused under a license type without In-Flight Masking. This 403 message appears only for those web UI create, update and delete actions:

In-Flight Masking is unavailable with the Sandbox license type. It is available with an Enterprise license.

Managing endpoints requires a license type that includes In-Flight Masking. See Licensing.

404 Not Found Responses Received

Problem

Requests that should return a normal response receive a "Not Found" response with 404 status code.

Solution

The ruleset plan's random suffix is not included in the URL

When a ruleset plan is created, the name specified has a random suffix appended. Check that the random suffix is included in the URL when attempting to edit its configuration or mask data. Refer to the Ruleset Plan Name Suffix Generation Documentation for more information.

The ruleset plan does not exist

The ruleset plan with the specified name does not exist (even with a valid suffix). Check for the ruleset plan in the ruleset plan list endpoint.

Check for trailing /s on URLs

All URLs must have a trailing /. For example https://<your-datamasque-instance>/ruleset-plans is not the same as https://<your-datamasque-instance>/ruleset-plans/. The latter with the trailing / is correct.

429 Too Many Requests Responses Received

Problem

Requests receive a 429 response with a body such as {"error": "Rate limit exceeded: 150 per 1 second"}.

Solution

Rate limit exceeded

Too many requests have been received by the in-flight server and have been rate limited. Refer to the Rate Limiting Documentation for more information.

Under a Sandbox license, the response body is {"error": "Rate limit exceeded: 6 per 1 minute"}. Mask requests are limited to 6 per minute across all users of the in-flight masking container, and the limit cannot be raised. Wait for the number of seconds in the Retry-After header before sending the next request, or install a license type that allows in-flight masking at the configured rate. See Sandbox license.

Other Error Responses Received

Problem

Error responses are returned, with 4xx or 5xx status codes.

Solution

Refer to API Reference for some common causes

The API reference includes some common status codes, with some common causes.

Refer to response body for logs

If an error response is returned, check the response body to see if the cause of the error is listed. Error messages are listed under error, detail or logs in the response body.

If the error occurs during a masking request, try replaying the request and specifying "log_level": "DEBUG" to get more log details in the response.

Check log files

More error detail may be available in the masque_in_flight_server.log. Refer to the configuration and logs documentation for more information.